feat(guestlinks)!: auth-guest service

.woodpecker.star

@@ -2482,6 +2482,7 @@ def opencloudServer(storage = "decomposed", depends_on = [], deploy_type = "", e
         "OC_TRANSLATION_PATH": "%s/tests/config/translations" % dirs["base"],
         "ACTIVITYLOG_WRITE_BUFFER_DURATION": "0",  # Disable write buffer so that test expectations are met in time
         "OC_LDAP_LOOKUP_CACHE_TTL": "0",  # disable ldap lookup cache so that test fixture change are applied right away
+        "OC_ENABLE_GUEST_LINKS": True,
         # search grpc port needed for index cli tests
         "SEARCH_GRPC_ADDR": "0.0.0.0:9220",
         # debug addresses required for running services health tests
@@ -2521,7 +2522,6 @@ def opencloudServer(storage = "decomposed", depends_on = [], deploy_type = "", e
         "WEBFINGER_DEBUG_ADDR": "0.0.0.0:9279",
         "STORAGE_USERS_POSIX_SCAN_DEBOUNCE_DELAY": 0,
         "OC_MACHINE_AUTH_API_KEY": MACHINE_AUTH_API_KEY,
-        "GRAPH_ENABLE_GUEST_INVITES": True,
     }
 
     if storage == "posix":

Makefile

@@ -30,6 +30,7 @@ OC_MODULES = \
 	services/auth-app \
 	services/auth-basic \
 	services/auth-bearer \
+	services/auth-guest \
 	services/auth-machine \
 	services/auth-service \
 	services/clientlog \

go.mod

@@ -39,6 +39,7 @@ require (
 	github.com/golang/protobuf v1.5.4
 	github.com/google/go-cmp v0.7.0
 	github.com/google/go-tika v0.3.1
+	github.com/google/renameio/v2 v2.0.2
 	github.com/google/uuid v1.6.0
 	github.com/gookit/config/v2 v2.2.9
 	github.com/gorilla/mux v1.8.1
@@ -235,7 +236,6 @@ require (
 	github.com/google/go-querystring v1.2.0 // indirect
 	github.com/google/go-tpm v0.9.8 // indirect
 	github.com/google/pprof v0.0.0-20260402051712-545e8a4df936 // indirect
-	github.com/google/renameio/v2 v2.0.2 // indirect
 	github.com/gookit/goutil v0.8.0 // indirect
 	github.com/gorilla/handlers v1.5.2 // indirect
 	github.com/gorilla/schema v1.4.1 // indirect

opencloud/pkg/command/services.go

@@ -15,6 +15,7 @@ import (
 	authapp "github.com/opencloud-eu/opencloud/services/auth-app/pkg/command"
 	authbasic "github.com/opencloud-eu/opencloud/services/auth-basic/pkg/command"
 	authbearer "github.com/opencloud-eu/opencloud/services/auth-bearer/pkg/command"
+	authguest "github.com/opencloud-eu/opencloud/services/auth-guest/pkg/command"
 	authmachine "github.com/opencloud-eu/opencloud/services/auth-machine/pkg/command"
 	authservice "github.com/opencloud-eu/opencloud/services/auth-service/pkg/command"
 	clientlog "github.com/opencloud-eu/opencloud/services/clientlog/pkg/command"
@@ -138,6 +139,11 @@ var serviceCommands = []register.Command{
 			cfg.Groups.Commons = cfg.Commons
 		})
 	},
+	func(cfg *config.Config) *cobra.Command {
+		return ServiceCommand(cfg, cfg.AuthGuest.Service.Name, authguest.GetCommands(cfg.AuthGuest), func(c *config.Config) {
+			cfg.AuthGuest.Commons = cfg.Commons
+		})
+	},
 	func(cfg *config.Config) *cobra.Command {
 		return ServiceCommand(cfg, cfg.IDM.Service.Name, idm.GetCommands(cfg.IDM), func(c *config.Config) {
 			cfg.IDM.Commons = cfg.Commons

opencloud/pkg/init/init.go

@@ -69,6 +69,7 @@ func CreateConfig(insecure, forceOverwrite, diff bool, configPath, adminPassword
 		idmServicePassword, idpServicePassword, ocAdminServicePassword, revaServicePassword  string
 		tokenManagerJwtSecret, collaborationWOPISecret, machineAuthAPIKey, systemUserAPIKey  string
 		revaTransferSecret, thumbnailsTransferSecret, serviceAccountSecret, urlSigningSecret string
+		authGuestJWTSecret                                                                   string
 		adminPasswdwordGenerated                                                             bool
 	)
 
@@ -103,6 +104,13 @@ func CreateConfig(insecure, forceOverwrite, diff bool, configPath, adminPassword
 				return fmt.Errorf("could not generate random secret for urlSigningSecret: %s", err)
 			}
 		}
+		authGuestJWTSecret = oldCfg.AuthGuest.TokenManager.JWTSecret
+		if authGuestJWTSecret == "" {
+			authGuestJWTSecret, err = generators.GenerateRandomPassword(passwordLength)
+			if err != nil {
+				return fmt.Errorf("could not generate random secret for authGuestJWTSecret: %s", err)
+			}
+		}
 	} else {
 		systemUserID = uuid.NewString()
 		adminUserID = uuid.NewString()
@@ -155,6 +163,10 @@ func CreateConfig(insecure, forceOverwrite, diff bool, configPath, adminPassword
 		if err != nil {
 			return fmt.Errorf("could not generate random secret for urlSigningSecret: %s", err)
 		}
+		authGuestJWTSecret, err = generators.GenerateRandomPassword(passwordLength)
+		if err != nil {
+			return fmt.Errorf("could not generate random secret for authGuestJWTSecret: %s", err)
+		}
 		thumbnailsTransferSecret, err = generators.GenerateRandomPassword(passwordLength)
 		if err != nil {
 			return fmt.Errorf("could not generate random password for thumbnailsTransferSecret: %s", err)
@@ -212,6 +224,10 @@ func CreateConfig(insecure, forceOverwrite, diff bool, configPath, adminPassword
 				},
 			},
 		},
+		AuthGuest: AuthGuest{
+			ServiceAccount: serviceAccount,
+			TokenManager:   TokenManager{JWTSecret: authGuestJWTSecret},
+		},
 		Users: UsersAndGroupsService{
 			Drivers: LdapBasedService{
 				Ldap: LdapSettings{

opencloud/pkg/init/structs.go

@@ -32,6 +32,7 @@ type OpenCloudConfig struct {
 	AuthBearer        AuthbearerService     `yaml:"auth_bearer"`
 	Users             UsersAndGroupsService `yaml:"users"`
 	Groups            UsersAndGroupsService `yaml:"groups"`
+	AuthGuest         AuthGuest             `yaml:"auth_guest"`
 	Ocm               OcmService            `yaml:"ocm"`
 	Thumbnails        ThumbnailService      `yaml:"thumbnails"`
 	Search            Search                `yaml:"search"`
@@ -53,6 +54,12 @@ type Activitylog struct {
 	ServiceAccount ServiceAccount `yaml:"service_account"`
 }
 
+// AuthGuest is the configuration for the auth-guest service
+type AuthGuest struct {
+	ServiceAccount ServiceAccount `yaml:"service_account"`
+	TokenManager   TokenManager   `yaml:"token_manager"`
+}
+
 // App is the configuration for the collaboration service
 type App struct {
 	Insecure bool `yaml:"insecure"`

opencloud/pkg/runtime/service/service.go

@@ -26,6 +26,7 @@ import (
 	audit "github.com/opencloud-eu/opencloud/services/audit/pkg/command"
 	authapp "github.com/opencloud-eu/opencloud/services/auth-app/pkg/command"
 	authbasic "github.com/opencloud-eu/opencloud/services/auth-basic/pkg/command"
+	authguest "github.com/opencloud-eu/opencloud/services/auth-guest/pkg/command"
 	authmachine "github.com/opencloud-eu/opencloud/services/auth-machine/pkg/command"
 	authservice "github.com/opencloud-eu/opencloud/services/auth-service/pkg/command"
 	clientlog "github.com/opencloud-eu/opencloud/services/clientlog/pkg/command"
@@ -198,6 +199,13 @@ func NewService(ctx context.Context, options ...Option) (*Service, error) {
 		cfg.Groups.Commons = cfg.Commons
 		return groups.Execute(cfg.Groups)
 	})
+	if opts.Config.Commons != nil && opts.Config.Commons.EnableGuestLinks {
+		reg(3, opts.Config.AuthGuest.Service.Name, func(ctx context.Context, cfg *occfg.Config) error {
+			cfg.AuthGuest.Context = ctx
+			cfg.AuthGuest.Commons = cfg.Commons
+			return authguest.Execute(cfg.AuthGuest)
+		})
+	}
 	reg(3, opts.Config.IDM.Service.Name, func(ctx context.Context, cfg *occfg.Config) error {
 		cfg.IDM.Context = ctx
 		cfg.IDM.Commons = cfg.Commons

pkg/config/config.go

@@ -10,6 +10,7 @@ import (
 	authapp "github.com/opencloud-eu/opencloud/services/auth-app/pkg/config"
 	authbasic "github.com/opencloud-eu/opencloud/services/auth-basic/pkg/config"
 	authbearer "github.com/opencloud-eu/opencloud/services/auth-bearer/pkg/config"
+	authguest "github.com/opencloud-eu/opencloud/services/auth-guest/pkg/config"
 	authmachine "github.com/opencloud-eu/opencloud/services/auth-machine/pkg/config"
 	authservice "github.com/opencloud-eu/opencloud/services/auth-service/pkg/config"
 	clientlog "github.com/opencloud-eu/opencloud/services/clientlog/pkg/config"
@@ -99,6 +100,7 @@ type Config struct {
 	Gateway           *gateway.Config        `yaml:"gateway"`
 	Graph             *graph.Config          `yaml:"graph"`
 	Groups            *groups.Config         `yaml:"groups"`
+	AuthGuest         *authguest.Config      `yaml:"auth_guest"`
 	IDM               *idm.Config            `yaml:"idm"`
 	IDP               *idp.Config            `yaml:"idp"`
 	Invitations       *invitations.Config    `yaml:"invitations"`

pkg/config/defaultconfig.go

@@ -10,6 +10,7 @@ import (
 	authapp "github.com/opencloud-eu/opencloud/services/auth-app/pkg/config/defaults"
 	authbasic "github.com/opencloud-eu/opencloud/services/auth-basic/pkg/config/defaults"
 	authbearer "github.com/opencloud-eu/opencloud/services/auth-bearer/pkg/config/defaults"
+	authguest "github.com/opencloud-eu/opencloud/services/auth-guest/pkg/config/defaults"
 	authmachine "github.com/opencloud-eu/opencloud/services/auth-machine/pkg/config/defaults"
 	authservice "github.com/opencloud-eu/opencloud/services/auth-service/pkg/config/defaults"
 	clientlog "github.com/opencloud-eu/opencloud/services/clientlog/pkg/config/defaults"
@@ -74,6 +75,7 @@ func DefaultConfig() *Config {
 		Gateway:           gateway.DefaultConfig(),
 		Graph:             graph.DefaultConfig(),
 		Groups:            groups.DefaultConfig(),
+		AuthGuest:         authguest.DefaultConfig(),
 		IDM:               idm.DefaultConfig(),
 		IDP:               idp.DefaultConfig(),
 		Invitations:       invitations.DefaultConfig(),

pkg/config/parser/parse.go

@@ -58,15 +58,15 @@ func EnsureDefaults(cfg *config.Config) {
 	if cfg.Reva == nil {
 		cfg.Reva = &shared.Reva{}
 	}
-}
 
-// EnsureCommons copies applicable parts of the OpenCloud config into the commons part
-func EnsureCommons(cfg *config.Config) {
 	// ensure the commons part is initialized
 	if cfg.Commons == nil {
 		cfg.Commons = &shared.Commons{}
 	}
+}
 
+// EnsureCommons copies applicable parts of the OpenCloud config into the commons part
+func EnsureCommons(cfg *config.Config) {
 	cfg.Commons.Log = structs.CopyOrZeroValue(cfg.Log)
 	cfg.Commons.Cache = structs.CopyOrZeroValue(cfg.Cache)
 

pkg/events/events.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	user "github.com/cs3org/go-cs3apis/cs3/identity/user/v1beta1"
+	collaboration "github.com/cs3org/go-cs3apis/cs3/sharing/collaboration/v1beta1"
 	provider "github.com/cs3org/go-cs3apis/cs3/storage/provider/v1beta1"
 )
 
@@ -20,3 +21,19 @@ func (ResourceMention) Unmarshal(v []byte) (interface{}, error) {
 	err := json.Unmarshal(v, &e)
 	return e, err
 }
+
+type GuestTokenCreated struct {
+	ShareID      *collaboration.ShareId
+	Sharer       *user.UserId
+	GranteeEmail string
+	ItemID       *provider.ResourceId
+	ResourceName string
+	Token        string
+	Timestamp    time.Time
+}
+
+func (GuestTokenCreated) Unmarshal(v []byte) (interface{}, error) {
+	e := GuestTokenCreated{}
+	err := json.Unmarshal(v, &e)
+	return e, err
+}

pkg/shared/shared_types.go

@@ -80,6 +80,7 @@ type Commons struct {
 	SystemUserAPIKey   string          `mask:"password" yaml:"system_user_api_key" env:"SYSTEM_USER_API_KEY" desc:"API key for all system users." introductionVersion:"1.0.0"`
 	AdminUserID        string          `yaml:"admin_user_id" env:"OC_ADMIN_USER_ID" desc:"ID of a user, that should receive admin privileges. Consider that the UUID can be encoded in some LDAP deployment configurations like in .ldif files. These need to be decoded beforehand." introductionVersion:"1.0.0"`
 	MultiTenantEnabled bool            `yaml:"multi_tenant_enabled" env:"OC_MULTI_TENANT_ENABLED" desc:"Set this to true to enable multi-tenant support." introductionVersion:"4.0.0"`
+	EnableGuestLinks   bool            `yaml:"enable_guest_links" env:"OC_ENABLE_GUEST_LINKS" desc:"Enables the guest links feature: creating shares to mail addresses and redeeming guest links. Disabled by default." introductionVersion:"%%NEXT%%"`
 
 	// NOTE: you will not fing GRPCMaxReceivedMessageSize size being used in the code. The envvar is actually extracted in revas `pool` package: https://github.com/cs3org/reva/blob/edge/pkg/rgrpc/todo/pool/connection.go
 	// It is mentioned here again so it is documented

services/auth-guest/.mockery.yaml

@@ -0,0 +1,14 @@
+# maintain v2 separate mocks dir
+dir: "{{.InterfaceDir}}/mocks"
+structname: "{{.InterfaceName}}"
+filename: "{{.InterfaceName | snakecase }}.go"
+pkgname: mocks
+
+template: testify
+packages:
+  github.com/opencloud-eu/opencloud/services/auth-guest/pkg/service/authguest:
+    interfaces:
+      AuthGuest: {}
+  github.com/opencloud-eu/opencloud/services/auth-guest/pkg/service/storage:
+    interfaces:
+      Manager: {}

services/auth-guest/Makefile

@@ -0,0 +1,15 @@
+SHELL := bash
+NAME := auth-guest
+
+ifneq (, $(shell command -v go 2> /dev/null)) # suppress `command not found warnings` for non go targets in CI
+include ../../.bingo/Variables.mk
+endif
+
+include ../../.make/default.mk
+include ../../.make/go.mk
+include ../../.make/release.mk
+include ../../.make/docs.mk
+
+.PHONY: go-generate
+go-generate: $(MOCKERY)
+	$(MOCKERY)

services/auth-guest/README.md

@@ -0,0 +1,101 @@
+# auth-guest
+
+The `auth-guest` service gives guest users access to a share without a full
+OpenCloud account. When a share is created for a user of type
+`USER_TYPE_GUEST`, the service issues a one-time guest link token; redeeming
+that token exchanges it for a signed session cookie that authenticates the
+guest.
+
+It is disabled by default. Set `OC_ENABLE_GUEST_LINKS=true` to enable the guest
+links feature and start the service.
+
+## Overview
+
+- **Consumes** the share lifecycle events `ShareCreated`, `ShareRemoved` and
+  `ShareExpired`.
+- **Publishes** the `GuestTokenCreated` event carrying the guest link token,
+  so the link can be delivered to the guest.
+- Exposes an unauthenticated endpoint that redeems the token and sets a
+  session cookie.
+- Stores only hashes of the token and deletes the stored record when the share
+  is removed or expires.
+
+## Guest links flow
+
+The following sequence diagram describes the guest links flow:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Guest user
+    participant Web as Web client
+    participant Redeem as Redeem endpoint
+    participant Proxy as OpenCloud proxy
+    participant Graph as Graph / sharedWithMe
+    participant DAV as WebDAV
+    participant Reva as Reva
+
+    User->>Web: Open guest link with valid token
+    Web->>+Redeem: Redeem Token
+    Note right of Redeem: Validate Token
+    Redeem->>+Reva: Get Share
+    Reva->>-Redeem: Share
+    Note right of Redeem: Validate Share, Mark Token used
+    Redeem->>-Web: Set Cookie, return shareid 
+    Note right of Web: HTTP only cookie with signed JWT (JWT lifetime 24h)
+    Web->>+Proxy: "/graph/me/drives/sharedWithMe"
+    Proxy->>+Reva: validate token extracted from JWT
+    Note right of Reva: Sign Reva Token for Guest User
+    Reva->>-Proxy: Authenticated
+    Proxy->>+Graph: "/graph/me/drives/sharedWithMe"
+    Note right of Proxy: Using Reva Token
+    Graph->>+Reva: Requests to ShareProvider
+    Reva->>-Graph: Shares
+    Graph->>-Proxy: driveItems (all shares for the Guest User)
+    Proxy->>-Web: driveItems
+    Note right of Web: Extracts driveItem for the specific share
+    Web->>+Proxy: PROPFIND (resource id extracted from driveItem)
+    Note right of Web: Using Cookie
+    Proxy->>+Reva: validate token extracted from JWT
+    Note right of Reva: Sign Reva Token for Guest User
+    Reva->>-Proxy: Authenticated
+    Proxy->>+DAV: PROPFIND
+    Note right of Proxy: Using Reva Token
+    DAV->>+Reva: Requests to StorageProvider
+    Reva->>-DAV: StorageProvider Responses
+    DAV->>-Proxy: PROPFIND Response
+    Proxy->>-Web: PROPFIND Response
+```
+
+## Token lifecycle
+
+1. **Issue** — on the consumed `ShareCreated` event, where the grantee is a
+   guest, the service generates a random secret and stores a record keyed by
+   the hash of the share id. It then publishes the `GuestTokenCreated` event
+   with the token.
+2. **Redeem** — the guest posts the token to
+   `POST /graph/v1beta1/extensions/org.libregraph/guestLinks/redeem`.
+    The service validates the token and the share, marks the token as used
+    and returns a signed JWT session token in a cookie plus the share's
+    `permissionId` in the response body. Tokens are single-use.
+3. **Cleanup** — on the consumed `ShareRemoved` or `ShareExpired` event, the
+   stored record is deleted.
+
+## Configuration
+
+The service is configured via `AUTH_GUEST_*` environment variables or a
+`auth-guest.yaml` file.
+
+To run only the HTTP part, set `AUTH_GUEST_EVENTS_DISABLED=true`. To run only
+the event consumer, set `AUTH_GUEST_HTTP_DISABLED=true`.
+
+Relevant options:
+
+- `AUTH_GUEST_JWT_SECRET` — secret used to sign session tokens.
+- `AUTH_GUEST_JWT_COOKIE_NAME`, `AUTH_GUEST_JWT_TTL` — session cookie name and
+  lifetime.
+- `AUTH_GUEST_TOKENS_STORAGE_ROOT` — where guest link token records are stored.
+- `AUTH_GUEST_SERVICE_ACCOUNT_ID`, `AUTH_GUEST_SERVICE_ACCOUNT_SECRET` — service
+  account used to query the gateway for share metadata.
+- `AUTH_GUEST_NUM_CONSUMERS` — number of concurrent event consumers.
+- `OC_REVA_GATEWAY` — CS3 gateway used to look up shares.

services/auth-guest/pkg/command/health.go

@@ -0,0 +1,21 @@
+// Copyright 2026 OpenCloud GmbH <mail@opencloud.eu>
+// SPDX-License-Identifier: Apache-2.0
+
+package command
+
+import (
+	"github.com/opencloud-eu/opencloud/services/auth-guest/pkg/config"
+	"github.com/spf13/cobra"
+)
+
+// Health is the entrypoint for the health command.
+func Health(cfg *config.Config) *cobra.Command {
+	return &cobra.Command{
+		Use:   "health",
+		Short: "Check health status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			// not implemented
+			return nil
+		},
+	}
+}