@spacefast/common 0.0.13 → 0.0.17

package/dist/contracts/access.d.ts

@@ -22,14 +22,29 @@ export declare function maxAccessRole(left: AccessRole | null, right: AccessRole
  * comments, and runtime authorization.
  */
 export declare function normalizeAccessScopePath(input: string): string;
-export declare const accessScopePathSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export declare const accessScopePathSchema: z.ZodString;
 export type AccessScopePath = z.infer<typeof accessScopePathSchema>;
 export declare function accessScopeContains(scope: string, path: string): boolean;
 export declare const authorityReferenceSchema: z.ZodString;
 export type AuthorityReference = z.infer<typeof authorityReferenceSchema>;
+export declare const accountPrincipalSchema: z.ZodString;
+export type AccountPrincipal = z.infer<typeof accountPrincipalSchema>;
+export declare const identifiedPrincipalSchema: z.ZodString;
+export type IdentifiedPrincipal = z.infer<typeof identifiedPrincipalSchema>;
+export declare const accessPrincipalSchema: z.ZodUnion<readonly [z.ZodLiteral<"anonymous">, z.ZodString]>;
+export type AccessPrincipal = z.infer<typeof accessPrincipalSchema>;
+export declare function accountPrincipal(userId: string): AccountPrincipal;
+/** The user id behind an account principal; null for anonymous or malformed. */
+export declare function accountPrincipalUserId(principal: string | undefined | null): string | null;
+/**
+ * The identity an authority reference names on its own, if any. Credential
+ * classes name nobody. This is the ONE place a class maps to an identity: at
+ * the exchange that just authenticated it, never downstream.
+ */
+export declare function principalForAuthority(reference: AuthorityReference): IdentifiedPrincipal | undefined;
 export declare const personGrantSchema: z.ZodObject<{
     id: z.ZodString;
-    scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    scope: z.ZodString;
     role: z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -59,7 +74,7 @@ export declare const spacePersonSchema: z.ZodObject<{
     }>;
     grants: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        scope: z.ZodString;
         role: z.ZodEnum<{
             viewer: "viewer";
             commenter: "commenter";
@@ -79,7 +94,7 @@ export type SpacePerson = z.infer<typeof spacePersonSchema>;
 export declare const inheritedTeamAccessSchema: z.ZodObject<{
     teamId: z.ZodString;
     teamName: z.ZodString;
-    ruleScopes: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    ruleScopes: z.ZodArray<z.ZodString>;
     members: z.ZodArray<z.ZodObject<{
         membershipId: z.ZodString;
         userId: z.ZodString;
@@ -103,7 +118,7 @@ export declare const spacePeopleListSchema: z.ZodObject<{
         }>;
         grants: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
-            scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            scope: z.ZodString;
             role: z.ZodEnum<{
                 viewer: "viewer";
                 commenter: "commenter";
@@ -122,7 +137,7 @@ export declare const spacePeopleListSchema: z.ZodObject<{
     inheritedTeamAccess: z.ZodNullable<z.ZodObject<{
         teamId: z.ZodString;
         teamName: z.ZodString;
-        ruleScopes: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        ruleScopes: z.ZodArray<z.ZodString>;
         members: z.ZodArray<z.ZodObject<{
             membershipId: z.ZodString;
             userId: z.ZodString;
@@ -138,11 +153,12 @@ export declare const accessShareLinkSchema: z.ZodObject<{
     id: z.ZodString;
     spaceId: z.ZodString;
     grantId: z.ZodString;
+    revision: z.ZodNumber;
     name: z.ZodString;
-    landingPath: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    landingPath: z.ZodString;
     resources: z.ZodObject<{
-        include: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     capabilities: z.ZodArray<z.ZodEnum<{
         "page.view": "page.view";
@@ -155,9 +171,9 @@ export declare const accessShareLinkSchema: z.ZodObject<{
         maxUses: z.ZodOptional<z.ZodNumber>;
         requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
         network: z.ZodOptional<z.ZodObject<{
-            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
             excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -184,11 +200,12 @@ export declare const accessShareLinkWithUrlSchema: z.ZodObject<{
     id: z.ZodString;
     spaceId: z.ZodString;
     grantId: z.ZodString;
+    revision: z.ZodNumber;
     name: z.ZodString;
-    landingPath: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    landingPath: z.ZodString;
     resources: z.ZodObject<{
-        include: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     capabilities: z.ZodArray<z.ZodEnum<{
         "page.view": "page.view";
@@ -201,9 +218,9 @@ export declare const accessShareLinkWithUrlSchema: z.ZodObject<{
         maxUses: z.ZodOptional<z.ZodNumber>;
         requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
         network: z.ZodOptional<z.ZodObject<{
-            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
             excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -227,6 +244,60 @@ export declare const accessShareLinkWithUrlSchema: z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>;
 export type AccessShareLinkWithUrl = z.infer<typeof accessShareLinkWithUrlSchema>;
+export declare const accessShareLinkReadSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    grantId: z.ZodString;
+    revision: z.ZodNumber;
+    name: z.ZodString;
+    landingPath: z.ZodString;
+    resources: z.ZodObject<{
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+    }>>;
+    constraints: z.ZodObject<{
+        notBefore: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        maxUses: z.ZodOptional<z.ZodNumber>;
+        requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
+        network: z.ZodOptional<z.ZodObject<{
+            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        branch: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"all_versions">;
+    }, z.core.$strict>], "kind">;
+    createdBy: z.ZodNullable<z.ZodString>;
+    openCount: z.ZodNumber;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    active: z.ZodBoolean;
+    url: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AccessShareLinkRead = z.infer<typeof accessShareLinkReadSchema>;
+export declare const publishedAccessSchema: z.ZodObject<{
+    url: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PublishedAccess = z.infer<typeof publishedAccessSchema>;
 export declare const canonicalAccessRequestStatusSchema: z.ZodEnum<{
     canceled: "canceled";
     expired: "expired";
@@ -247,7 +318,7 @@ export declare const canonicalAccessRequestSchema: z.ZodObject<{
     spaceId: z.ZodString;
     displayName: z.ZodNullable<z.ZodString>;
     email: z.ZodString;
-    scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    scope: z.ZodString;
     requestedRole: z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -287,7 +358,7 @@ export type LinkCapabilities = z.infer<typeof linkCapabilitiesSchema>;
 export declare const spacePersonInviteWriteSchema: z.ZodObject<{
     email: z.ZodString;
     grants: z.ZodArray<z.ZodObject<{
-        scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        scope: z.ZodString;
         role: z.ZodEnum<{
             viewer: "viewer";
             commenter: "commenter";
@@ -297,7 +368,7 @@ export declare const spacePersonInviteWriteSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const personGrantWriteSchema: z.ZodObject<{
-    scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    scope: z.ZodString;
     role: z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -307,7 +378,7 @@ export declare const personGrantWriteSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const spacePersonGrantSetWriteSchema: z.ZodObject<{
     grants: z.ZodArray<z.ZodObject<{
-        scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        scope: z.ZodString;
         role: z.ZodEnum<{
             viewer: "viewer";
             commenter: "commenter";
@@ -318,10 +389,10 @@ export declare const spacePersonGrantSetWriteSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const accessShareLinkCreateSchema: z.ZodObject<{
     name: z.ZodString;
-    landingPath: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    landingPath: z.ZodDefault<z.ZodString>;
     resources: z.ZodObject<{
-        include: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         "page.view": "page.view";
@@ -334,9 +405,9 @@ export declare const accessShareLinkCreateSchema: z.ZodObject<{
         maxUses: z.ZodOptional<z.ZodNumber>;
         requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
         network: z.ZodOptional<z.ZodObject<{
-            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
             excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -353,11 +424,12 @@ export declare const accessShareLinkCreateSchema: z.ZodObject<{
     }, z.core.$strict>], "kind">>;
 }, z.core.$strip>;
 export declare const accessShareLinkUpdateSchema: z.ZodObject<{
+    expectedRevision: z.ZodNumber;
     name: z.ZodOptional<z.ZodString>;
-    landingPath: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    landingPath: z.ZodOptional<z.ZodString>;
     resources: z.ZodOptional<z.ZodObject<{
-        include: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         "page.view": "page.view";
@@ -365,16 +437,16 @@ export declare const accessShareLinkUpdateSchema: z.ZodObject<{
         "comments.write": "comments.write";
     }>>>;
     constraints: z.ZodOptional<z.ZodObject<{
-        notBefore: z.ZodOptional<z.ZodString>;
-        expiresAt: z.ZodOptional<z.ZodString>;
-        maxUses: z.ZodOptional<z.ZodNumber>;
-        requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
-        network: z.ZodOptional<z.ZodObject<{
-            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-            excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
+        notBefore: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        maxUses: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        requireVerifiedEmail: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        network: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            ipCidrs: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            countries: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            excludedCountries: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            excludedUserAgentSubstrings: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"live">;
@@ -390,7 +462,7 @@ export declare const accessShareLinkUpdateSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
     email: z.ZodString;
-    scope: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    scope: z.ZodString;
     requestedRole: z.ZodDefault<z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -400,7 +472,7 @@ export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
     message: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const canonicalAccessRequestApproveSchema: z.ZodObject<{
-    scope: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    scope: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
@@ -417,11 +489,31 @@ export declare const openHandoffSchema: z.ZodObject<{
         claim_preview: "claim_preview";
     }>;
 }, z.core.$strip>;
+export declare const openLinkSchema: z.ZodObject<{
+    url: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"link">;
+}, z.core.$strip>;
+export declare const privateOpenSchema: z.ZodUnion<readonly [z.ZodObject<{
+    url: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"link">;
+}, z.core.$strip>, z.ZodObject<{
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+    kind: z.ZodEnum<{
+        management: "management";
+        person: "person";
+        claim_preview: "claim_preview";
+    }>;
+}, z.core.$strip>]>;
 export declare const openHandoffCreateSchema: z.ZodObject<{
-    landingPath: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    landingPath: z.ZodDefault<z.ZodString>;
     targetHost: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type OpenHandoff = z.infer<typeof openHandoffSchema>;
+export type OpenLink = z.infer<typeof openLinkSchema>;
+export type PrivateOpen = z.infer<typeof privateOpenSchema>;
 export declare const teamSpaceAccessDefaultSchema: z.ZodObject<{
     newSpaceGrantPreset: z.ZodEnum<{
         team: "team";
@@ -439,8 +531,15 @@ export declare const teamSpaceAccessDefaultWriteSchema: z.ZodObject<{
 export declare const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export declare const ACCESS_TOKEN_ALG = "EdDSA";
 export declare const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
+export declare const accessTokenPublicProfileSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    avatar_url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+export type AccessTokenPublicProfile = z.infer<typeof accessTokenPublicProfileSchema>;
 export declare const accessTokenPayloadSchema: z.ZodObject<{
     sub: z.ZodString;
+    principal: z.ZodOptional<z.ZodString>;
     authorities: z.ZodArray<z.ZodString>;
     exp: z.ZodNumber;
     nbf: z.ZodNumber;
@@ -448,8 +547,14 @@ export declare const accessTokenPayloadSchema: z.ZodObject<{
     iss: z.ZodString;
     aud: z.ZodString;
     spaceId: z.ZodString;
+    sid: z.ZodString;
     generation: z.ZodNumber;
     emailVerified: z.ZodDefault<z.ZodBoolean>;
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        avatar_url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
     jti: z.ZodString;
 }, z.core.$strip>;
 export type AccessTokenPayload = z.infer<typeof accessTokenPayloadSchema>;

package/dist/contracts/access.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { grantConstraintsSchema, grantResourceSetSchema, grantTargetSelectorSchema, } from "./grants.js";
+import { grantConstraintsPatchSchema, grantConstraintsSchema, grantResourceSetSchema, grantTargetSelectorSchema, } from "./grants.js";
 // ---------------------------------------------------------------------------
 // Canonical sharing model
 // ---------------------------------------------------------------------------
@@ -74,16 +74,16 @@ export const accessScopePathSchema = z
     .string()
     .min(1)
     .max(1024)
-    .transform((value, context) => {
+    .check((context) => {
     try {
-        return normalizeAccessScopePath(value);
+        context.value = normalizeAccessScopePath(context.value);
     }
     catch (error) {
-        context.addIssue({
+        context.issues.push({
             code: "custom",
+            input: context.value,
             message: error instanceof Error ? error.message : "invalid access scope",
         });
-        return z.NEVER;
     }
 });
 export function accessScopeContains(scope, path) {
@@ -96,6 +96,40 @@ export function accessScopeContains(scope, path) {
 export const authorityReferenceSchema = z
     .string()
     .regex(/^(member|person|link|password|machine|claim-preview|external):[A-Za-z0-9_.-]+$/);
+// WHO a session is, orthogonal to WHAT it may do. A session has exactly one
+// principal and any number of authorities; neither implies the other. A member
+// who arrives by share link is still that member, and a link authority alone
+// never makes someone anonymous.
+export const accountPrincipalSchema = z.string().regex(/^account:[A-Za-z0-9_-]+$/);
+// The three kinds of somebody. `account:` is a Spacefast user. `person:` is
+// someone this Space invited by email and who accepted — a real, named identity
+// with no platform account behind it. `external:` is a subject an identity
+// connection vouched for. Anything else — a share Link, a password, a machine
+// key, a claim preview — authenticates no one: those sessions stay anonymous
+// and carry the credential purely as an authority.
+export const identifiedPrincipalSchema = z
+    .string()
+    .regex(/^(?:account|person|external):[A-Za-z0-9_.-]+$/);
+export const accessPrincipalSchema = z.union([z.literal("anonymous"), identifiedPrincipalSchema]);
+export function accountPrincipal(userId) {
+    return accountPrincipalSchema.parse(`account:${userId}`);
+}
+/** The user id behind an account principal; null for anonymous or malformed. */
+export function accountPrincipalUserId(principal) {
+    if (!principal || !accountPrincipalSchema.safeParse(principal).success)
+        return null;
+    return principal.slice("account:".length);
+}
+/**
+ * The identity an authority reference names on its own, if any. Credential
+ * classes name nobody. This is the ONE place a class maps to an identity: at
+ * the exchange that just authenticated it, never downstream.
+ */
+export function principalForAuthority(reference) {
+    return reference.startsWith("person:") || reference.startsWith("external:")
+        ? identifiedPrincipalSchema.parse(reference)
+        : undefined;
+}
 export const personGrantSchema = z.object({
     id: z.string().min(1),
     scope: accessScopePathSchema,
@@ -128,7 +162,7 @@ export const inheritedTeamAccessSchema = z.object({
     ruleScopes: z
         .array(accessScopePathSchema)
         .min(1)
-        .describe("Explicit Team rule locations, not effective subtree coverage."),
+        .describe("Explicit team rule locations, not effective subtree coverage."),
     members: z.array(z.object({
         membershipId: z.string().min(1),
         userId: z.string().min(1),
@@ -146,6 +180,7 @@ export const accessShareLinkSchema = z.object({
     id: z.string().min(1),
     spaceId: z.string().min(1),
     grantId: z.string().min(1),
+    revision: z.number().int().positive(),
     name: z.string().min(1),
     landingPath: accessScopePathSchema,
     resources: grantResourceSetSchema,
@@ -162,6 +197,21 @@ export const accessShareLinkSchema = z.object({
 export const accessShareLinkWithUrlSchema = accessShareLinkSchema.extend({
     url: z.string().url(),
 });
+// Reads re-derive the durable branded URL from the sealed token. Links minted
+// before branded URLs existed report null until the backfill mints theirs,
+// rather than pretending to hold a URL that would not open.
+export const accessShareLinkReadSchema = accessShareLinkSchema.extend({
+    url: z.string().url().nullable(),
+});
+// The publish receipt exposes one durable access capability in both of its
+// useful transports: a browser entry URL and the raw token integrations send
+// in X-SF-Authorization. It is access to published bytes, never proof of
+// ownership; claim credentials stay a separate receipt field.
+export const publishedAccessSchema = z.object({
+    url: z.string().url(),
+    token: z.string().min(16).max(512),
+    expiresAt: z.string().datetime().nullable(),
+});
 export const canonicalAccessRequestStatusSchema = z.enum([
     "verification_pending",
     "pending",
@@ -216,16 +266,19 @@ export const accessShareLinkCreateSchema = z.object({
     name: z.string().trim().min(1).max(200),
     landingPath: accessScopePathSchema.default("/"),
     resources: grantResourceSetSchema,
-    capabilities: linkCapabilitiesSchema.default(["page.view"]),
+    // Anonymous commenting is a product default: a Link that names no
+    // capabilities admits reading the page and leaving a comment.
+    capabilities: linkCapabilitiesSchema.default(["page.view", "comments.read", "comments.write"]),
     constraints: grantConstraintsSchema.default({}),
     target: grantTargetSelectorSchema.default({ kind: "live" }),
 });
 export const accessShareLinkUpdateSchema = z.object({
+    expectedRevision: z.number().int().positive(),
     name: z.string().trim().min(1).max(200).optional(),
     landingPath: accessScopePathSchema.optional(),
     resources: grantResourceSetSchema.optional(),
     capabilities: linkCapabilitiesSchema.optional(),
-    constraints: grantConstraintsSchema.optional(),
+    constraints: grantConstraintsPatchSchema.optional(),
     target: grantTargetSelectorSchema.optional(),
 });
 export const canonicalAccessRequestCreateSchema = z.object({
@@ -243,6 +296,12 @@ export const openHandoffSchema = z.object({
     expiresAt: z.string().datetime(),
     kind: z.enum(["management", "claim_preview", "person"]),
 });
+export const openLinkSchema = z.object({
+    url: z.string().url(),
+    expiresAt: z.string().datetime().nullable(),
+    kind: z.literal("link"),
+});
+export const privateOpenSchema = z.union([openLinkSchema, openHandoffSchema]);
 export const openHandoffCreateSchema = z.object({
     landingPath: accessScopePathSchema.default("/"),
     targetHost: z.string().trim().min(1).max(255).optional(),
@@ -259,8 +318,31 @@ export const teamSpaceAccessDefaultWriteSchema = z.object({
 export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export const ACCESS_TOKEN_ALG = "EdDSA";
 export const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
+// Public identity attached only when a token consumer needs to render the
+// person behind an authority. Collaboration tickets carry this audience-bound
+// claim so Cast can paint an avatar without ever seeing an address: the
+// minting side normalizes a provider avatar or derives one from the email,
+// then drops the email. Raw email and provider-private profile metadata never
+// belong here.
+export const accessTokenPublicProfileSchema = z
+    .object({
+    name: z.string().min(1).max(120).optional(),
+    username: z.string().min(1).max(160).optional(),
+    avatar_url: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .optional(),
+})
+    .strict();
 export const accessTokenPayloadSchema = z.object({
     sub: authorityReferenceSchema,
+    // Who this handoff authenticated, when it authenticated anybody. The account
+    // lane names the signed-in user; the invite and identity-connection lanes
+    // name the Person or external subject they just proved. Link, password,
+    // machine, and claim-preview lanes never set it, and its absence means the
+    // runtime session is anonymous. Identity comes from here alone — never
+    // inferred from the authority classes below.
+    principal: identifiedPrincipalSchema.optional(),
     authorities: z.array(authorityReferenceSchema).min(1).max(16),
     exp: z.number().int().nonnegative(),
     nbf: z.number().int().nonnegative(),
@@ -268,7 +350,11 @@ export const accessTokenPayloadSchema = z.object({
     iss: z.string().min(1),
     aud: z.string().min(1),
     spaceId: z.string().min(1),
+    // Shared opaque identity for the runtime session and its access-origin
+    // collaboration session. It is random per handoff and never authorizes by itself.
+    sid: z.string().regex(/^[a-f0-9]{64}$/),
     generation: z.number().int().nonnegative(),
     emailVerified: z.boolean().default(false),
+    profile: accessTokenPublicProfileSchema.optional(),
     jti: z.string().min(1),
 });

package/dist/contracts/activity.js

@@ -193,7 +193,11 @@ export const activityQuerySchema = cursorListQuerySchema.extend({
         .describe("Filter to events owned by a team or an external customer principal."),
     principalId: z.string().min(1).optional().describe("Filter to a single principal id."),
     spaceId: z.string().min(1).optional().describe("Filter to events for one space."),
-    code: z.string().min(1).optional().describe("Filter to one event code, e.g. `space.created`."),
+    code: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to one event code, for example `space.created`."),
     since: z.string().datetime().optional().describe("Only events at or after this time."),
     until: z.string().datetime().optional().describe("Only events at or before this time."),
 });

package/dist/contracts/api-keys.js

@@ -48,7 +48,7 @@ export const StatticActionSchema = z.enum([
     "runtime:manage",
     "*",
 ]);
-const DescribedStatticActionSchema = StatticActionSchema.describe("A namespaced IAM-lite action (`noun:verb`) or `*` for all actions.");
+const DescribedStatticActionSchema = StatticActionSchema.describe("Namespaced IAM-lite action (`noun:verb`), or `*` for all actions.");
 const RESOURCE_PREFIX = "stt://tenant/";
 function isResourceSegment(value) {
     return Boolean(value && value.length > 0 && !/[\s/\\]/.test(value));
@@ -100,7 +100,7 @@ const StatticResourceSchema = z
     .refine((value) => parseStatticResource(value) !== null, {
     message: "Resource must be a stt:// URI from the StatticResource union (tenant, principal, site, space, site space, domain, or domain-group).",
 })
-    .describe("A resource URI from the StatticResource union: stt://tenant/{t}, …/principal/(team|external)/{id}[/*], …/site/{id}[/*], …/space/{id}[/*], …/site/{id}/space/{id}[/*], …/domain/{id}, or …/domain-group/{id}.");
+    .describe("Resource URI from the resource union: stt://tenant/{t}, …/principal/(team|external)/{id}[/*], …/site/{id}[/*], …/space/{id}[/*], …/site/{id}/space/{id}[/*], …/domain/{id}, or …/domain-group/{id}.");
 export const ApiCredentialPolicySchema = z
     .object({
     version: z
@@ -129,11 +129,11 @@ export const ApiCredentialPolicySchema = z
         })
             .strict()
             .optional()
-            .describe("ANDed condition attributes. Unresolvable attributes fail closed: no-match for allow, match for deny."),
+            .describe("AND condition attributes. Unresolvable attributes fail closed: no match for allow, and match for deny."),
     })
         .strict())
         .min(1)
-        .describe("Evaluation: explicit deny wins, explicit allow permits, otherwise implicit deny."),
+        .describe("Evaluation order: explicit deny wins, explicit allow permits, otherwise implicit deny."),
 })
     .strict()
     .describe("IAM-lite access policy evaluated for every credentialed request.");
@@ -147,12 +147,12 @@ export const ApiKeyPresetSchema = z
     "team_admin",
     "billing_viewer",
 ])
-    .describe("Named policy preset compiled into a concrete access policy at key creation.");
+    .describe("Named policy preset compiled into a concrete access policy when the key is created.");
 // `system` is never a principal type: runtime/internal credentials are
 // platform-owned and omit ownerPrincipal entirely (internal-docs/platform.md).
 const ApiKeyOwnerPrincipalSchema = z.object({
     type: z.enum(["team", "external"]).describe("Principal type that owns this key."),
-    id: z.string().min(1).describe("Stable principal id (Better Auth team id or external id)."),
+    id: z.string().min(1).describe("Stable principal id (Better Auth team id, or external id)."),
 });
 const ApiKeySubjectSchema = z.object({
     type: z
@@ -190,7 +190,7 @@ export const ApiKeyListQuerySchema = cursorListQuerySchema.extend({
         .string()
         .min(1)
         .optional()
-        .describe("Owning team whose keys to list. Defaults to the caller's own team; any team the credential's policy reaches is allowed."),
+        .describe("Owning team whose keys to list. Defaults to the caller's own team. Any team that the credential policy reaches is allowed."),
 });
 export const ApiKeyListResponseSchema = z.object({
     data: z.array(ApiKeySchema),
@@ -202,7 +202,7 @@ export const ApiKeyCreateRequestSchema = z.object({
         .string()
         .min(1)
         .optional()
-        .describe("Owning team for the new key. Defaults to the caller's own team; authorization is by the credential's policy, not key ownership."),
+        .describe("Owning team for the new key. Defaults to the caller's own team. Authorization is by the credential policy, not key ownership."),
     preset: ApiKeyPresetSchema.optional(),
     policy: ApiCredentialPolicySchema.nullable()
         .optional()
@@ -252,7 +252,7 @@ export const ApiKeyScopeSchema = z
     z.object({ kind: z.literal("team"), teamId: z.string().min(1) }).strict(),
     z.object({ kind: z.literal("space"), spaceId: z.string().min(1) }).strict(),
 ])
-    .describe("Explicit, finite policy target. A space scope narrows the derived policy to exactly that space — never the owning team's whole tree.");
+    .describe("Explicit, finite policy target. A space scope narrows the derived policy to exactly that space, never the owning team's whole tree.");
 export const ApiKeyScopedCreateRequestSchema = z
     .object({
     name: z.string().trim().min(1).max(255).optional().describe("Human-readable key name."),