Help us shape the future of Go! Take the 2026 Go Developer Survey

spec

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package spec defines OCM wire-format types (discovery, shares, invites, errors). See https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md?plain=1#ocm-api-discovery

Index

Constants

View Source 
const (
	CapabilityHTTPSig       = "http-sig"
	CapabilityExchangeToken = "exchange-token"
	CapabilityInvite        = "invites"
	CapabilityInviteWAYF    = "invite-wayf"
	CapabilityNotifications = wire.CapabilityNotifications
)

Canonical OCM discovery capability wire values (IETF-RFC / OpenAPI).

Invites dual-plane: outbound.EndpointInvites is an endpoint/type-plane concept for outbound POST targets, while CapabilityInvite is the discovery wire capability value. Keep those planes distinct even when the literal string coincides.

View Source 
const (
	CriteriaMustUseHTTPSig    = "must-use-http-sig"
	CriteriaMustExchangeToken = "must-exchange-token"
	CriteriaDenylist          = "denylist"
	CriteriaAllowlist         = "allowlist"
	CriteriaMustInvite        = "must-invite"
)

Canonical OCM discovery criteria wire values. Enum: spec.yaml:525-530 https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/spec.yaml#L525-L530; denylist/allowlist semantics: IETF-OCM.md:759-762 https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md#L759-L762.

View Source 
const (
	// NotificationTypeShareAccepted is sent when a receiver accepts a share.
	NotificationTypeShareAccepted = "SHARE_ACCEPTED"
	// NotificationTypeShareDeclined is sent when a receiver declines a share.
	NotificationTypeShareDeclined = "SHARE_DECLINED"
	// NotificationTypeShareUnshared is sent when the sender revokes a share.
	NotificationTypeShareUnshared = "SHARE_UNSHARED"
)
View Source 
const (
	ProtocolWebDAV        = wire.ProtocolWebDAV
	ProtocolWebDAVReceive = "webdav-receive"
)

ProtocolWebDAV and ProtocolWebDAVReceive are the canonical OCM discovery protocol role keys.

View Source 
const (
	RequirementMustExchangeToken = "must-exchange-token"

	// RequirementMustUseMFA is recognized only to be hard-rejected at admit;
	// MFA enforcement is not supported.
	RequirementMustUseMFA = "must-use-mfa"
)

Canonical OCM protocol requirement wire values (IETF-RFC / OpenAPI). Used on share WebDAV/webapp arms and by access/admission call sites.

View Source 
const (
	ErrorInvalidRequest       = "invalid_request"
	ErrorInvalidGrant         = "invalid_grant"
	ErrorInvalidClient        = "invalid_client"
	ErrorUnauthorized         = "unauthorized_client"
	ErrorUnsupportedGrantType = "unsupported_grant_type"
	ErrorServerError          = "server_error"
)

OAuth error codes.

View Source 
const APIVersionPin = "1.4.0"

APIVersionPin is the Layer 1 wire pin for OCM discovery apiVersion.

View Source 
const (
	GrantTypeAuthorizationCode = "authorization_code"
)

GrantType constants.

View Source 
const SignatureLabelOCM = sigparams.SignatureLabelOCM

SignatureLabelOCM is the RFC 9421 dictionary label for OCM HTTP signatures.

Variables

View Source 
var SupportedNotificationTypes = []string{
	NotificationTypeShareAccepted,
	NotificationTypeShareDeclined,
	NotificationTypeShareUnshared,
}

SupportedNotificationTypes lists the core notification types implemented by ocmgo.

View Source 
var SupportedResourceTypes = []string{"file"}

SupportedResourceTypes are the OCM resource types accepted for share creation. Only "file" is supported: ocm-go serves a single read-only file via singleFileFS; folder shares are not implemented. See the OCM-API share-creation contract: https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md?plain=1

View Source 
var SupportedWebDAVAccessTypes = []string{"remote"}

SupportedWebDAVAccessTypes are the WebDAV access type values this implementation currently recognizes.

View Source 
var SupportedWebDAVPermissions = []string{"read"}

SupportedWebDAVPermissions are the WebDAV permission values this implementation currently honors.

View Source 
var SupportedWebDAVRequirements = []string{RequirementMustExchangeToken}

SupportedWebDAVRequirements are the WebDAV protocol requirement values this implementation currently recognizes.

View Source 
var SupportedWebappPermissions = []string{"view", "read", "write", "share"}

SupportedWebappPermissions are the webapp protocol permission values this implementation honors at admit. They are intentionally distinct from SupportedWebDAVPermissions: webapp admits view/read/write/share, while WebDAV currently admits only read. Do not merge the two lists.

View Source 
var SupportedWebappRequirements = []string{RequirementMustExchangeToken, RequirementMustUseMFA}

SupportedWebappRequirements lists the webapp requirement tokens this implementation recognizes. The name is kept for consistency with the other Supported* lists, but only must-exchange-token is admitted; must-use-mfa is listed solely to be hard-rejected at admit because MFA enforcement is not supported.

Functions

func IsSupportedResourceType added in v1.2.0 

func IsSupportedResourceType(resourceType string) bool

IsSupportedResourceType reports whether resourceType is accepted for share creation.

func KnownCriteria added in v1.2.0 

func KnownCriteria() []string

KnownCriteria returns the five OCM spec criteria wire values.

func ResolveInviteAcceptDialog added in v1.1.0 

func ResolveInviteAcceptDialog(baseURL, dialog string) string

ResolveInviteAcceptDialog resolves a relative inviteAcceptDialog against baseURL.

func ValidateProtocolArms added in v1.2.0 

func ValidateProtocolArms(raw map[string]json.RawMessage) error

ValidateProtocolArms is the protocol-arm admission hook. It admits the supported arm keys: name (the protocol shape selector), webdav, and webapp. Any other key is rejected as UNSUPPORTED.

func WriteOCMError 

func WriteOCMError(w http.ResponseWriter, status int, message string)

WriteOCMError writes a base Error schema response (no validationErrors).

func WriteProtocolNotSupported 

func WriteProtocolNotSupported(w http.ResponseWriter)

WriteProtocolNotSupported writes a 501 response for unsupported protocols.

func WriteResourceTypeNotSupported added in v1.2.0 

func WriteResourceTypeNotSupported(w http.ResponseWriter)

WriteResourceTypeNotSupported writes a 501 response for unsupported resource types.

func WriteShareTypeNotSupported 

func WriteShareTypeNotSupported(w http.ResponseWriter)

WriteShareTypeNotSupported writes a 501 response for unsupported share types.

func WriteValidationError 

func WriteValidationError(w http.ResponseWriter, message string, errors []ValidationError)

WriteValidationError writes a 400 OCM error response with the given message and validation errors.

Types

type CreateShareResponse 

type CreateShareResponse struct {
	RecipientDisplayName string `json:"recipientDisplayName"`
}

CreateShareResponse carries the wire body returned after creating a share.

type Discovery 

type Discovery struct {
	Enabled            bool           `json:"enabled"`
	APIVersion         string         `json:"apiVersion"`
	EndPoint           string         `json:"endPoint"`
	Provider           string         `json:"provider,omitempty"`
	ResourceTypes      []ResourceType `json:"resourceTypes"`
	Capabilities       []string       `json:"capabilities,omitempty"`
	Criteria           []string       `json:"criteria"`                     // Always present, serializes as [] when empty
	TokenEndPoint      string         `json:"tokenEndPoint,omitempty"`      // Required when exchange-token capability is advertised
	JwksUri            string         `json:"jwksUri,omitempty"`            //nolint:revive // wire field name matches OCM spec jwksUri
	InviteAcceptDialog string         `json:"inviteAcceptDialog,omitempty"` // URL for the invite-accept dialog (WAYF)
	Warnings           []string       `json:"-"`
}

Discovery holds the OCM discovery document served by GET /ocm/.

func (*Discovery) BuildWebDAVURL 

func (d *Discovery) BuildWebDAVURL(shareID string) (string, error)

BuildWebDAVURL constructs the full WebDAV URL for accessing a share.

func (*Discovery) GetEndpoint 

func (d *Discovery) GetEndpoint() string

func (*Discovery) GetWebDAVPath 

func (d *Discovery) GetWebDAVPath() string

GetWebDAVPath returns the WebDAV protocol path for the "file" resource type, or empty if absent.

func (*Discovery) HasCapability 

func (d *Discovery) HasCapability(capability string) bool

HasCapability reports whether the discovery advertises the given capability.

func (*Discovery) HasCriteria 

func (d *Discovery) HasCriteria(criterion string) bool

HasCriteria reports whether the discovery lists the given criterion.

func (*Discovery) IsHTTPSigCapable added in v1.1.0 

func (d *Discovery) IsHTTPSigCapable() bool

IsHTTPSigCapable reports whether the peer advertises the http-sig capability.

func (*Discovery) RequiresHTTPSig added in v1.1.0 

func (d *Discovery) RequiresHTTPSig() bool

RequiresHTTPSig reports whether the peer requires signed OCM requests per the IETF must-use-http-sig criterion.

func (*Discovery) SupportsTokenExchange added in v1.1.0 

func (d *Discovery) SupportsTokenExchange() bool

SupportsTokenExchange reports whether the peer advertises a complete token-exchange capability set (capability + token endpoint).

func (*Discovery) WebDAVReceiveURIKind added in v1.2.0 

func (d *Discovery) WebDAVReceiveURIKind() WebDAVReceiveURIKind

WebDAVReceiveURIKind reports the remote webdav-receive uri kind when advertised.

type DiscoveryPaths added in v1.1.0 

type DiscoveryPaths struct {
	EndPoint           string
	TokenEndPoint      string
	JwksURI            string
	WebDAVRoot         string
	InviteAcceptDialog string
}

DiscoveryPaths holds route-derived discovery path fields before policy overlays.

func DeriveDiscoveryPaths added in v1.1.0 

func DeriveDiscoveryPaths(id localidentity.Identity, opts service.RouteOpts) (DiscoveryPaths, bool)

DeriveDiscoveryPaths projects discovery path fields from local identity and Routes(opts). ok is true when Origin is set and the OCM protocol endPoint could be projected.

type InviteAcceptedRequest 

type InviteAcceptedRequest struct {
	RecipientProvider string `json:"recipientProvider"`
	Token             string `json:"token"`
	UserID            string `json:"userID"` //nolint:tagliatelle // OCM-API spec mandates 'userID' (capital ID), not camelCase 'userId'
	Email             string `json:"email"`
	Name              string `json:"name"`
}

InviteAcceptedRequest carries the wire body for POST /ocm/invite-accepted. See https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md?plain=1#invite-acceptance-response-details

type InviteAcceptedResponse 

type InviteAcceptedResponse struct {
	UserID string `json:"userID"` //nolint:tagliatelle // OCM-API spec mandates 'userID' (capital ID), not camelCase 'userId'
	Email  string `json:"email"`
	Name   string `json:"name"`
}

InviteAcceptedResponse carries the wire body returned for an accepted invite.

type NewShareRequest 

type NewShareRequest struct {
	ShareWith         string   `json:"shareWith"`
	Name              string   `json:"name"`
	Description       string   `json:"description,omitempty"`
	ProviderID        string   `json:"providerId"`
	Owner             string   `json:"owner"`
	Sender            string   `json:"sender"`
	OwnerDisplayName  string   `json:"ownerDisplayName,omitempty"`
	SenderDisplayName string   `json:"senderDisplayName,omitempty"`
	ShareType         string   `json:"shareType"`
	ResourceType      string   `json:"resourceType"`
	Expiration        *int64   `json:"expiration,omitempty"`
	Protocol          Protocol `json:"protocol"`
}

NewShareRequest carries the wire body for POST /ocm/shares. See the OCM-API share-creation contract: https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md?plain=1

type NotificationRequest added in v1.2.0 

type NotificationRequest struct {
	NotificationType string          `json:"notificationType"`
	ProviderID       string          `json:"providerId"`
	ResourceType     string          `json:"resourceType,omitempty"`
	Notification     json.RawMessage `json:"notification,omitempty"`
}

NotificationRequest carries the wire body for POST /ocm/notifications. See https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md

type OAuthError 

type OAuthError struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"` //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
}

OAuthError represents an OAuth-style error response.

type OCMErrorResponse 

type OCMErrorResponse struct {
	Message          string            `json:"message"`
	ValidationErrors []ValidationError `json:"validationErrors,omitempty"`
}

OCMErrorResponse carries the message and optional validation errors written for failed OCM requests.

type Protocol 

type Protocol struct {
	Name   string          `json:"name,omitempty"`
	WebDAV *WebDAVProtocol `json:"webdav,omitempty"`
	Webapp *WebappProtocol `json:"webapp,omitempty"`
}

Protocol carries the named protocol arm of a share request (webdav or webapp).

type ProtocolRole added in v1.2.0 

type ProtocolRole struct {
	// contains filtered or unexported fields
}

ProtocolRole is either a string path/address or a structured JSON object.

func ObjectProtocolRole added in v1.2.0 

func ObjectProtocolRole(v any) (ProtocolRole, error)

ObjectProtocolRole marshals v as a JSON object protocol role.

func StringProtocolRole added in v1.2.0 

func StringProtocolRole(s string) ProtocolRole

StringProtocolRole constructs a string-valued protocol role.

func WebDAVReceiveRole added in v1.2.0 

func WebDAVReceiveRole(uri WebDAVReceiveURIKind) ProtocolRole

WebDAVReceiveRole constructs a webdav-receive protocol role.

func (ProtocolRole) MarshalJSON added in v1.2.0 

func (p ProtocolRole) MarshalJSON() ([]byte, error)

MarshalJSON encodes the role as its string or object JSON form; implements json.Marshaler.

func (ProtocolRole) StringValue added in v1.2.0 

func (p ProtocolRole) StringValue() (string, bool)

StringValue returns the string form when the role is string-valued.

func (*ProtocolRole) UnmarshalJSON added in v1.2.0 

func (p *ProtocolRole) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a string or object JSON value into the role; implements json.Unmarshaler.

func (ProtocolRole) WebDAVReceive added in v1.2.0 

func (p ProtocolRole) WebDAVReceive() (*WebDAVReceive, bool)

WebDAVReceive decodes a webdav-receive object role.

type Protocols added in v1.2.0 

type Protocols map[string]ProtocolRole

Protocols maps OCM protocol role names to string or object values.

func (Protocols) StringRole added in v1.2.0 

func (p Protocols) StringRole(name string) (string, bool)

StringRole returns a string-valued role by name.

func (Protocols) WebDAVReceive added in v1.2.0 

func (p Protocols) WebDAVReceive() (*WebDAVReceive, bool)

WebDAVReceive returns a webdav-receive role when present.

type ResourceType 

type ResourceType struct {
	Name       string    `json:"name"`
	ShareTypes []string  `json:"shareTypes"`
	Protocols  Protocols `json:"protocols"`
}

ResourceType describes one entry in the discovery resourceTypes list.

type TokenRequest 

type TokenRequest struct {
	GrantType string `json:"grant_type"` //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
	ClientID  string `json:"client_id"`  //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
	Code      string `json:"code"`
}

TokenRequest represents an incoming token exchange request (form-urlencoded).

type TokenResponse 

type TokenResponse struct {
	AccessToken string `json:"access_token"` //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
	TokenType   string `json:"token_type"`   //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
	ExpiresIn   int    `json:"expires_in"`   //nolint:tagliatelle // RFC 6749 mandates snake_case for OAuth 2.0 token endpoint fields
}

TokenResponse represents a successful token exchange response.

type ValidationError 

type ValidationError struct {
	Name    string `json:"name"`
	Message string `json:"message"`
}

ValidationError carries one field-level validation error in an OCM error response. See the OCM-API share-creation contract: https://github.com/cs3org/OCM-API/blob/6a0586183cbef10ecae9dedc42561806447eb2f5/IETF-OCM.md?plain=1

func ValidateNotificationRequest added in v1.2.0 

func ValidateNotificationRequest(req *NotificationRequest) []ValidationError

ValidateNotificationRequest returns validation errors for a notification request.

func ValidateProtocolShape added in v1.2.0 

func ValidateProtocolShape(p Protocol) *ValidationError

ValidateProtocolShape checks the minimal current-purpose protocol shape. The named "webdav" shape requires a webdav arm. The "multi" shape requires at least one supported arm: webdav or webapp. This admits a webapp-only arm under "multi" without altering the named "webdav" shape behavior.

func ValidateRequiredFields 

func ValidateRequiredFields(req *NewShareRequest) []ValidationError

ValidateRequiredFields returns ValidationError for each missing spec-required NewShare field. protocol.name handled by handler.

func ValidateWebDAVProtocol added in v1.2.0 

func ValidateWebDAVProtocol(p *WebDAVProtocol) []ValidationError

ValidateWebDAVProtocol is the strict wrapper: wire validation plus requirements admission with localRequires=true.

func ValidateWebDAVProtocolWire added in v1.2.0 

func ValidateWebDAVProtocolWire(p *WebDAVProtocol) []ValidationError

ValidateWebDAVProtocolWire checks WebDAV wire fields only: uri, sharedSecret, and permissions are required; permissions and accessTypes (when present) must be in this implementation's supported lists; unknown requirements return UNSUPPORTED. Empty requirements are valid on the wire.

func ValidateWebDAVRequirementsAdmission added in v1.2.0 

func ValidateWebDAVRequirementsAdmission(localRequires bool, reqs []string) []ValidationError

ValidateWebDAVRequirementsAdmission applies the criteria-aware requirements seam. When localRequires is true, empty requirements are REQUIRED; when false, empty requirements produce no admission error. Non-empty requirements produce no admission error either way (wire validation covers unknown values).

func ValidateWebappProtocol added in v1.2.0 

func ValidateWebappProtocol(p *WebappProtocol) []ValidationError

ValidateWebappProtocol is the strict wrapper: wire validation plus requirements admission with localRequires=true. Admission errors that already appear identically from wire are skipped so empty requirements still yield a single REQUIRED error.

func ValidateWebappProtocolWire added in v1.2.0 

func ValidateWebappProtocolWire(p *WebappProtocol) []ValidationError

ValidateWebappProtocolWire checks webapp wire fields: uri, targets, permissions, and sharedSecret are required; permissions must be in SupportedWebappPermissions; unknown requirements return UNSUPPORTED; must-use-mfa is hard-rejected at admit because MFA enforcement is not supported. must-exchange-token remains REQUIRED on the wire; the criteria-aware admission seam does not relax that check.

func ValidateWebappRequirementsAdmission added in v1.2.0 

func ValidateWebappRequirementsAdmission(localRequires bool, reqs []string) []ValidationError

ValidateWebappRequirementsAdmission applies the criteria-aware requirements seam. When localRequires is true, empty requirements are REQUIRED; when false, empty requirements produce no admission error. Non-empty requirements produce no admission error either way. This does not replace wire checks for must-exchange-token.

type WebDAVProtocol 

type WebDAVProtocol struct {
	AccessTypes  []string `json:"accessTypes,omitempty"`
	URI          string   `json:"uri"`
	SharedSecret string   `json:"sharedSecret,omitempty"`
	Permissions  []string `json:"permissions"`
	Requirements []string `json:"requirements,omitempty"`
}

WebDAVProtocol carries the WebDAV protocol fields of a share request.

func (*WebDAVProtocol) HasRequirement 

func (p *WebDAVProtocol) HasRequirement(req string) bool

HasRequirement reports whether the WebDAV arm advertises req.

type WebDAVReceive added in v1.2.0 

type WebDAVReceive struct {
	URI WebDAVReceiveURIKind `json:"uri"`
}

WebDAVReceive is the structured webdav-receive protocol role.

type WebDAVReceiveURIKind added in v1.2.0 

type WebDAVReceiveURIKind string

WebDAVReceiveURIKind is the uri field of a webdav-receive protocol role. 

const (
	// WebDAVReceiveURIAbsolute is the absolute WebDAV receive URI kind.
	WebDAVReceiveURIAbsolute WebDAVReceiveURIKind = "absolute"
	// WebDAVReceiveURIRelative is the relative WebDAV receive URI kind.
	WebDAVReceiveURIRelative WebDAVReceiveURIKind = "relative"
)

type WebappProtocol added in v1.2.0 

type WebappProtocol struct {
	URI          string   `json:"uri"`
	Targets      []string `json:"targets"`
	Permissions  []string `json:"permissions"`
	Requirements []string `json:"requirements"`
	SharedSecret string   `json:"sharedSecret"`
}

WebappProtocol is the webapp protocol arm. Its permissions are distinct from WebDAV permissions (see SupportedWebappPermissions) and must not be merged into a shared permissions list. sharedSecret is IETF REQUIRED at admit time, so it has no omitempty here; the redacted outbound-view exception is handled at the outbound redaction layer and is out of scope here.

func (*WebappProtocol) HasRequirement added in v1.2.0 

func (p *WebappProtocol) HasRequirement(req string) bool

HasRequirement reports whether the webapp arm advertises req.

Source Files

View all Source files

Directories

Path Synopsis
Package wire holds leaf OCM wire-protocol string constants that the parent spec package re-exports.
 Package wire holds leaf OCM wire-protocol string constants that the parent spec package re-exports.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.