@productcraft/platform-auth 0.0.8 → 0.0.9

package/dist/index.d.ts

@@ -74,6 +74,40 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/auth/oauth/{provider}/callback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Complete a federated sign-in. auth-ui proxies the provider redirect (query params for Google/GitHub, form_post body for Apple) into this endpoint and uses the returned `tokens` to set the auth_token cookie. */
+        post: operations["OAuthController_callback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/oauth/{provider}/start": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Begin a federated sign-in flow; 302s to the provider authorize URL. */
+        get: operations["OAuthController_start"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/auth/password/request-reset": {
         parameters: {
             query?: never;
@@ -210,6 +244,58 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/me": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read the caller's account profile. */
+        get: operations["MeController_getMe"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/me/avatar": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Upload (or replace) the caller's avatar. PNG/JPEG/WEBP only — SVG is rejected because user-uploaded SVG from a productcraft.co origin is a stored-XSS vector. ≤2 MB. Magic bytes are sniffed; a mislabeled file is rejected. */
+        post: operations["MeController_setAvatar"];
+        /** Clear the caller's avatar and delete the stored object. */
+        delete: operations["MeController_removeAvatar"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/me/profile": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /** Update the caller's profile. Currently only `displayName` is editable. An empty body is a no-op that returns the current profile. Cookie/JWT only — this is a human-self-service surface, not a PAK-mutation surface. */
+        patch: operations["MeController_updateProfile"];
+        trace?: never;
+    };
     "/v1/session": {
         parameters: {
             query?: never;
@@ -271,7 +357,7 @@ interface paths {
         /** List workspaces the current user belongs to */
         get: operations["WorkspaceController_listWorkspaces"];
         put?: never;
-        /** Create a new workspace */
+        /** Create a new workspace. Cookie/JWT only — PAKs are workspace-scoped credentials and cannot create new workspaces. */
         post: operations["WorkspaceController_createWorkspace"];
         delete?: never;
         options?: never;
@@ -288,7 +374,7 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Accept a workspace invite by code */
+        /** Accept a workspace invite by code. Cookie/JWT only — invite acceptance binds a human identity to a workspace. */
         post: operations["WorkspaceController_acceptInvite"];
         delete?: never;
         options?: never;
@@ -307,11 +393,11 @@ interface paths {
         get: operations["WorkspaceController_getWorkspace"];
         put?: never;
         post?: never;
-        /** Delete a workspace (requires workspace.delete) */
+        /** Delete a workspace (requires workspace.delete). Cookie/JWT only — irreversible workspace destruction needs a human-attributed audit row. */
         delete: operations["WorkspaceController_deleteWorkspace"];
         options?: never;
         head?: never;
-        /** Update workspace display name, slug, or settings. Slug renames broadcast a `workspace.renamed` event so denormalised consumers (rally-api) sync. */
+        /** Update workspace display name, slug, or settings. Slug renames broadcast a `workspace.renamed` event so denormalised consumers (waitlist-api) sync. */
         patch: operations["WorkspaceController_updateWorkspace"];
         trace?: never;
     };
@@ -325,7 +411,7 @@ interface paths {
         /** List PAKs in this workspace. Plaintext tokens are NOT returned — only prefixes + metadata. */
         get: operations["PlatformApiKeyController_list"];
         put?: never;
-        /** Mint a new PAK. The plaintext `token` is returned ONCE — store it now. The minter can grant at most their own effective permissions. */
+        /** Mint a new PAK. The plaintext `token` is returned ONCE — store it now. The minter can grant at most their own effective permissions. Cookie/JWT only — PAKs cannot mint other PAKs. */
         post: operations["PlatformApiKeyController_create"];
         delete?: never;
         options?: never;
@@ -406,6 +492,24 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_slug}/avatar": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Upload (or replace) the workspace identity avatar. Gated by `workspace.settings.update` (owner + admin). PNG/JPEG/WEBP only, ≤2 MB, magic-byte sniffed. SVG is rejected (stored-XSS). */
+        post: operations["WorkspaceController_setAvatar"];
+        /** Clear the workspace avatar and delete the stored object. Gated by `workspace.settings.update`. */
+        delete: operations["WorkspaceController_removeAvatar"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_slug}/invites": {
         parameters: {
             query?: never;
@@ -416,7 +520,7 @@ interface paths {
         /** List workspace invites */
         get: operations["WorkspaceController_listInvites"];
         put?: never;
-        /** Create a workspace invite link */
+        /** Create a workspace invite link. Cookie/JWT only — invites bring new humans into the workspace. */
         post: operations["WorkspaceController_createInvite"];
         delete?: never;
         options?: never;
@@ -434,7 +538,7 @@ interface paths {
         get?: never;
         put?: never;
         post?: never;
-        /** Revoke a workspace invite */
+        /** Revoke a workspace invite. Cookie/JWT only. */
         delete: operations["WorkspaceController_revokeInvite"];
         options?: never;
         head?: never;
@@ -502,7 +606,7 @@ interface paths {
         /** List every managed policy in a workspace */
         get: operations["WorkspacePolicyController_list"];
         put?: never;
-        /** Create a managed policy */
+        /** Create a managed policy. Cookie/JWT only — policy authoring is a human-admin surface. */
         post: operations["WorkspacePolicyController_create"];
         delete?: never;
         options?: never;
@@ -538,11 +642,11 @@ interface paths {
         get: operations["WorkspacePolicyController_get"];
         put?: never;
         post?: never;
-        /** Delete a managed policy. Cascades: API keys lose the binding (deny-all if no other bindings remain); roles fall back to their inline policy column. */
+        /** Delete a managed policy. Cascades: API keys lose the binding (deny-all if no other bindings remain); roles fall back to their inline policy column. Cookie/JWT only. */
         delete: operations["WorkspacePolicyController_delete"];
         options?: never;
         head?: never;
-        /** Update a managed policy */
+        /** Update a managed policy. Cookie/JWT only — policy authoring is a human-admin surface. */
         patch: operations["WorkspacePolicyController_update"];
         trace?: never;
     };
@@ -556,7 +660,7 @@ interface paths {
         /** List all roles in a workspace */
         get: operations["WorkspaceRoleController_list"];
         put?: never;
-        /** Create a new custom role */
+        /** Create a new custom role. Cookie/JWT only — role authoring is a human-admin surface. */
         post: operations["WorkspaceRoleController_create"];
         delete?: never;
         options?: never;
@@ -575,11 +679,11 @@ interface paths {
         get: operations["WorkspaceRoleController_get"];
         put?: never;
         post?: never;
-        /** Delete a custom role (fails if it has members) */
+        /** Delete a custom role (fails if it has members). Cookie/JWT only — role authoring is a human-admin surface. */
         delete: operations["WorkspaceRoleController_delete"];
         options?: never;
         head?: never;
-        /** Update a role or replace its permission set */
+        /** Update a role or replace its permission set. Cookie/JWT only — role authoring is a human-admin surface. */
         patch: operations["WorkspaceRoleController_update"];
         trace?: never;
     };
@@ -651,6 +755,9 @@ interface components {
             /** @description Per-source diagnostics so the UI / customer can see which sources contributed to this page and which are stubbed pending the cross-service fanout. */
             sources: components["schemas"]["SourceDiagnosticDto"][];
         };
+        AvatarUrlResponseDto: {
+            avatar_url: string;
+        };
         BoundPolicySummaryDto: {
             description: string | null;
             /** Format: uuid */
@@ -658,6 +765,16 @@ interface components {
             /** @example envoi-readonly */
             name: string;
         };
+        CallbackBodyDto: {
+            /** @description OAuth authorization code returned by the IdP. Optional — either `idToken` or `code` must be supplied. */
+            code?: string;
+            /** @description JWT id_token from the IdP (OIDC providers; Apple form_post). Optional — either `idToken` or `code` must be supplied. */
+            id_token?: string;
+            /** @description Opaque state token returned by the IdP, minted at `/start`. Single-use; binds the callback to a specific browser session. */
+            state: string;
+            /** @description Apple-only first-signin payload: JSON-encoded `{ name, email }`. Apple returns this only the first time a user signs in. Not signed — treated as untrusted input by the controller's payload parser. */
+            user?: string;
+        };
         CreatePakDto: {
             /** @description Optional description (e.g. which service uses the key). */
             description?: string;
@@ -726,8 +843,8 @@ interface components {
              * @example [
              *       {
              *         "actions": [
-             *           "envoi.read",
-             *           "envoi.list"
+             *           "mail.read",
+             *           "mail.list"
              *         ],
              *         "effect": "allow",
              *         "resources": [
@@ -751,7 +868,7 @@ interface components {
              * @example [
              *       {
              *         "actions": [
-             *           "envoi.*.read"
+             *           "mail.*.read"
              *         ],
              *         "effect": "allow",
              *         "resources": [
@@ -809,6 +926,8 @@ interface components {
             message: string;
         };
         IntrospectAccountDto: {
+            /** @description Public HTTPS URL of the uploaded avatar, or null when no avatar is set. */
+            avatar_url: string | null;
             display_name: string | null;
             email: string | null;
             /**
@@ -853,6 +972,8 @@ interface components {
             name: string;
         };
         IntrospectWorkspaceListItemDto: {
+            /** @description Workspace identity avatar (public HTTPS URL), or null when none is set. Console workspace switcher reads this. */
+            avatar_url: string | null;
             display_name: string;
             /** Format: uuid */
             id: string;
@@ -990,6 +1111,22 @@ interface components {
             /** Format: uuid */
             workspace_id: string;
         };
+        MeProfileDto: {
+            /** @description Short-lived (15 min) presigned GET URL for the avatar object in private object storage. NULL when no avatar has been set; the frontend then renders initials. The API mints a fresh URL on every response, so a stable bookmark of this value is not meaningful. */
+            avatar_url: string | null;
+            display_name: string | null;
+            email: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp when this account verified its primary email, or null if unverified.
+             */
+            email_verified_at: string | null;
+            /** Format: uuid */
+            id: string;
+            /** @description Account status (e.g. `active`, `suspended`). */
+            status: string;
+            username: string;
+        };
         MintPakResponseDto: {
             record: components["schemas"]["PublicApiKeyDto"];
             /**
@@ -998,6 +1135,12 @@ interface components {
              */
             token: string;
         };
+        OAuthCallbackResultDto: {
+            /** @description Original `return_to` the user was sent off with. auth-ui redirects here after writing the cookie. */
+            return_to: string;
+            /** @description Issued PlatformUser session tokens. auth-ui sets the auth_token cookie from `accessToken` and 302s the browser to `return_to`. */
+            tokens: components["schemas"]["TokenResponseDto"];
+        };
         PaginationDto: {
             /** @example false */
             has_more: boolean;
@@ -1014,8 +1157,8 @@ interface components {
             /**
              * @description Action strings the statement applies to. Wildcards (e.g. `agora.*`, `*.read`, `*`) supported per `actionMatches` semantics.
              * @example [
-             *       "agora.read",
-             *       "agora.list"
+             *       "social.read",
+             *       "social.list"
              *     ]
              */
             actions: string[];
@@ -1231,12 +1374,16 @@ interface components {
             description?: string | null;
             name?: string;
         };
+        UpdateProfileDto: {
+            /** @description New display name. 1-128 chars. Optional — empty PATCH is a no-op. */
+            display_name?: string;
+        };
         UpdateWorkspaceDto: {
             display_name?: string;
             /** @description Free-form workspace settings blob. */
             settings?: Record<string, never>;
             /**
-             * @description New URL-friendly slug. Same constraints as the create form. Renames are broadcast on the workspace events queue so denormalised consumers (rally-api, future product surfaces) can sync. Old URLs continue to resolve for one rename cycle.
+             * @description New URL-friendly slug. Same constraints as the create form. Renames are broadcast on the workspace events queue so denormalised consumers (waitlist-api, future product surfaces) can sync. Old URLs continue to resolve for one rename cycle.
              * @example acme
              */
             slug?: string;
@@ -1257,8 +1404,8 @@ interface components {
              * @example [
              *       {
              *         "actions": [
-             *           "envoi.read",
-             *           "envoi.list"
+             *           "mail.read",
+             *           "mail.list"
              *         ],
              *         "effect": "allow",
              *         "resources": [
@@ -1320,6 +1467,9 @@ interface components {
             /** Format: uuid */
             workspace_id: string;
         };
+        WorkspaceAvatarUrlResponseDto: {
+            avatar_url: string;
+        };
         WorkspaceInviteListItemDto: {
             /** @description Single-use invite code embedded in the invite URL. */
             code: string;
@@ -1581,6 +1731,76 @@ interface operations {
             };
         };
     };
+    OAuthController_callback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                provider: "apple" | "google" | "github";
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CallbackBodyDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OAuthCallbackResultDto"];
+                };
+            };
+            /** @description Unknown / expired state, provider state mismatch, or unknown provider id. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Provider token verification failed, nonce replayed, or downstream identity could not be resolved. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    OAuthController_start: {
+        parameters: {
+            query: {
+                /** @description Absolute URL the user lands on after a successful signin. Must match the `OAUTH_RETURN_TO_ORIGINS` allowlist (CSV, wildcards supported as `https://*.productcraft.co`). */
+                return_to: string;
+            };
+            header?: never;
+            path: {
+                /** @description OAuth provider id. Providers are gated on env-var configuration; unconfigured providers 400 with UNKNOWN_OAUTH_PROVIDER. */
+                provider: "apple" | "google" | "github";
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Redirect to provider authorize URL. */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Invalid `return_to` or unknown provider. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     PasswordController_requestPasswordReset: {
         parameters: {
             query?: never;
@@ -1779,6 +1999,151 @@ interface operations {
             };
         };
     };
+    MeController_getMe: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MeProfileDto"];
+                };
+            };
+            /** @description No session. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No account row for the session principal. Should never fire for a valid session — surfaced for SDKs. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    MeController_setAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    /**
+                     * Format: binary
+                     * @description PNG, JPEG, or WEBP image, ≤2 MB.
+                     */
+                    file: string;
+                };
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AvatarUrlResponseDto"];
+                };
+            };
+            /** @description Invalid file: wrong mimetype, oversized, or content does not match the declared type. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No session. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    MeController_removeAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Avatar removed (or already absent). */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No session. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    MeController_updateProfile: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateProfileDto"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MeProfileDto"];
+                };
+            };
+            /** @description Validation failed (e.g. displayName outside 1-128 chars). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No session. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The caller authenticated with a non-human principal (e.g. PAK). Profile is per-human; only the human owner can mutate their own row. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     SessionController_getSessions: {
         parameters: {
             query?: never;
@@ -1907,6 +2272,13 @@ interface operations {
                     "application/json": components["schemas"]["WorkspaceResponseDto"];
                 };
             };
+            /** @description Caller is a PAK (`pcft_live_*`). Workspace creation requires a human-issued session. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     WorkspaceController_acceptInvite: {
@@ -1972,6 +2344,13 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description Caller is a PAK (`pcft_live_*`). Workspace deletion requires a human-issued session. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     WorkspaceController_updateWorkspace: {
@@ -2065,6 +2444,13 @@ interface operations {
                     "application/json": components["schemas"]["MintPakResponseDto"];
                 };
             };
+            /** @description Caller is a PAK (`pcft_live_*`). Mint requires a human-issued session. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     PlatformApiKeyController_get: {
@@ -2269,6 +2655,64 @@ interface operations {
             };
         };
     };
+    WorkspaceController_setAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    /**
+                     * Format: binary
+                     * @description PNG, JPEG, or WEBP image, ≤2 MB. Square images look best.
+                     */
+                    file: string;
+                };
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkspaceAvatarUrlResponseDto"];
+                };
+            };
+            /** @description Caller is not a member of this workspace, or lacks workspace.settings.update. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    WorkspaceController_removeAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Avatar cleared. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     WorkspaceController_listInvites: {
         parameters: {
             query: {