@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/frame-session.d.ts

@@ -0,0 +1,192 @@
+import { z } from "zod";
+export declare const frameTargetV1Schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"live">;
+    versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+    routeRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"version">;
+    versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"branch">;
+    branch: z.ZodString;
+    versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+    branchRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+}, z.core.$strict>], "kind">;
+export type FrameTargetV1 = z.infer<typeof frameTargetV1Schema>;
+export declare const framePrincipalV1Schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"anonymous">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    id: z.ZodString;
+    assertionNonce: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type FramePrincipalV1 = z.infer<typeof framePrincipalV1Schema>;
+export declare const frameAudienceV1Schema: z.ZodObject<{
+    spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+    runtimeInstanceId: z.ZodString;
+    host: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+}, z.core.$strict>;
+export type FrameAudienceV1 = z.infer<typeof frameAudienceV1Schema>;
+export declare const frameLinkRevisionV1Schema: z.ZodObject<{
+    id: z.ZodTemplateLiteral<`lnk_${string}`>;
+    revision: z.ZodNumber;
+}, z.core.$strict>;
+export type FrameLinkRevisionV1 = z.infer<typeof frameLinkRevisionV1Schema>;
+export declare const frameGrantDecisionV1Schema: z.ZodObject<{
+    format: z.ZodLiteral<"spacefast.frame-grant-decision">;
+    version: z.ZodLiteral<1>;
+    audience: z.ZodObject<{
+        spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+        runtimeInstanceId: z.ZodString;
+        host: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    }, z.core.$strict>;
+    link: z.ZodObject<{
+        id: z.ZodTemplateLiteral<`lnk_${string}`>;
+        revision: z.ZodNumber;
+    }, z.core.$strict>;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"anonymous">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+        assertionNonce: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        routeRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        branch: z.ZodString;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        branchRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>], "kind">;
+    surface: z.ZodEnum<{
+        "wordpress.editor": "wordpress.editor";
+        "wordpress.preview": "wordpress.preview";
+    }>;
+    parentOrigin: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+        "content.publish": "content.publish";
+        "access.manage": "access.manage";
+    }>>;
+    accessGeneration: z.ZodNumber;
+    sessionVersion: z.ZodNumber;
+}, z.core.$strict>;
+export type FrameGrantDecisionV1 = z.infer<typeof frameGrantDecisionV1Schema>;
+export declare const frameLaunchTicketClaimsV1Schema: z.ZodObject<{
+    format: z.ZodLiteral<"spacefast.frame-launch-ticket">;
+    version: z.ZodLiteral<1>;
+    ticketId: z.ZodString;
+    flow: z.ZodEnum<{
+        launch: "launch";
+        renewal: "renewal";
+    }>;
+    maxUses: z.ZodLiteral<1>;
+    audience: z.ZodObject<{
+        spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+        runtimeInstanceId: z.ZodString;
+        host: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    }, z.core.$strict>;
+    link: z.ZodObject<{
+        id: z.ZodTemplateLiteral<`lnk_${string}`>;
+        revision: z.ZodNumber;
+    }, z.core.$strict>;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"anonymous">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+        assertionNonce: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        routeRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        branch: z.ZodString;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        branchRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>], "kind">;
+    surface: z.ZodEnum<{
+        "wordpress.editor": "wordpress.editor";
+        "wordpress.preview": "wordpress.preview";
+    }>;
+    parentOrigin: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+        "content.publish": "content.publish";
+        "access.manage": "access.manage";
+    }>>;
+    grantDecisionDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    accessGeneration: z.ZodNumber;
+    sessionVersion: z.ZodNumber;
+    issuedAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+export type FrameLaunchTicketClaimsV1 = z.infer<typeof frameLaunchTicketClaimsV1Schema>;
+export declare const frameSessionClaimsV1Schema: z.ZodObject<{
+    format: z.ZodLiteral<"spacefast.frame-session">;
+    version: z.ZodLiteral<1>;
+    launchTicketId: z.ZodString;
+    audience: z.ZodObject<{
+        spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+        runtimeInstanceId: z.ZodString;
+        host: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    }, z.core.$strict>;
+    link: z.ZodObject<{
+        id: z.ZodTemplateLiteral<`lnk_${string}`>;
+        revision: z.ZodNumber;
+    }, z.core.$strict>;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"anonymous">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+        assertionNonce: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        routeRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        branch: z.ZodString;
+        versionId: z.ZodTemplateLiteral<`ver_${string}`>;
+        branchRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    }, z.core.$strict>], "kind">;
+    surface: z.ZodEnum<{
+        "wordpress.editor": "wordpress.editor";
+        "wordpress.preview": "wordpress.preview";
+    }>;
+    parentOrigin: z.core.$ZodBranded<z.ZodString, "ExactOrigin", "out">;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+        "content.publish": "content.publish";
+        "access.manage": "access.manage";
+    }>>;
+    grantDecisionDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    accessGeneration: z.ZodNumber;
+    sessionVersion: z.ZodNumber;
+    nonce: z.ZodString;
+    issuedAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+export type FrameSessionClaimsV1 = z.infer<typeof frameSessionClaimsV1Schema>;

package/dist/contracts/frame-session.js

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { contentProgramSha256Schema } from "./content-program.js";
+import { grantCapabilitySchema } from "./grants.js";
+import { registeredIdSchema } from "./ids.js";
+import { exactOriginSchema } from "./principal-assertion.js";
+export const frameTargetV1Schema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("live"),
+        versionId: registeredIdSchema("ver"),
+        routeRevision: contentProgramSha256Schema,
+    })
+        .strict(),
+    z.object({ kind: z.literal("version"), versionId: registeredIdSchema("ver") }).strict(),
+    z
+        .object({
+        kind: z.literal("branch"),
+        branch: z.string().min(1).max(255),
+        versionId: registeredIdSchema("ver"),
+        branchRevision: contentProgramSha256Schema,
+    })
+        .strict(),
+]);
+export const framePrincipalV1Schema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("anonymous") }).strict(),
+    z
+        .object({
+        kind: z.literal("user"),
+        id: z.string().min(1).max(255),
+        assertionNonce: z.string().min(16).max(512),
+    })
+        .strict(),
+]);
+export const frameAudienceV1Schema = z
+    .object({
+    spaceId: registeredIdSchema("spc"),
+    runtimeInstanceId: z.string().min(1).max(255),
+    host: exactOriginSchema,
+})
+    .strict();
+// A Link's public revision is the positive integer generation on its owned
+// Grant. Editing or revoking the Link increments that generation. Frame tokens
+// bind the number directly so the runtime can compare it with the current
+// projection without translating a second revision scheme.
+export const frameLinkRevisionV1Schema = z
+    .object({
+    id: registeredIdSchema("lnk"),
+    revision: z.number().int().positive(),
+})
+    .strict();
+function validateFrameAuthority(claims, context, subject) {
+    if (!claims.capabilities.includes("page.view")) {
+        context.addIssue({
+            code: "custom",
+            path: ["capabilities"],
+            message: `${subject} require page.view`,
+        });
+    }
+    if (new Set(claims.capabilities).size !== claims.capabilities.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["capabilities"],
+            message: "capabilities must be unique",
+        });
+    }
+    if (claims.surface === "wordpress.editor" && claims.principal.kind === "anonymous") {
+        context.addIssue({
+            code: "custom",
+            path: ["principal"],
+            message: "WordPress editor Frames require a durable principal",
+        });
+    }
+    if (claims.surface === "wordpress.editor" && !claims.capabilities.includes("content.publish")) {
+        context.addIssue({
+            code: "custom",
+            path: ["capabilities"],
+            message: "WordPress editor Frames require content.publish",
+        });
+    }
+}
+export const frameGrantDecisionV1Schema = z
+    .object({
+    format: z.literal("spacefast.frame-grant-decision"),
+    version: z.literal(1),
+    audience: frameAudienceV1Schema,
+    link: frameLinkRevisionV1Schema,
+    principal: framePrincipalV1Schema,
+    target: frameTargetV1Schema,
+    surface: z.enum(["wordpress.editor", "wordpress.preview"]),
+    parentOrigin: exactOriginSchema,
+    capabilities: z.array(grantCapabilitySchema).min(1).max(5),
+    accessGeneration: z.number().int().nonnegative(),
+    sessionVersion: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((decision, context) => validateFrameAuthority(decision, context, "Frame Grant decisions"));
+export const frameLaunchTicketClaimsV1Schema = z
+    .object({
+    format: z.literal("spacefast.frame-launch-ticket"),
+    version: z.literal(1),
+    ticketId: z.string().min(16).max(512),
+    flow: z.enum(["launch", "renewal"]),
+    maxUses: z.literal(1),
+    audience: frameAudienceV1Schema,
+    link: frameLinkRevisionV1Schema,
+    principal: framePrincipalV1Schema,
+    target: frameTargetV1Schema,
+    surface: z.enum(["wordpress.editor", "wordpress.preview"]),
+    parentOrigin: exactOriginSchema,
+    capabilities: z.array(grantCapabilitySchema).min(1).max(5),
+    grantDecisionDigest: contentProgramSha256Schema,
+    accessGeneration: z.number().int().nonnegative(),
+    sessionVersion: z.number().int().nonnegative(),
+    issuedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().positive(),
+})
+    .strict()
+    .superRefine((ticket, context) => {
+    if (ticket.expiresAt <= ticket.issuedAt || ticket.expiresAt - ticket.issuedAt > 60) {
+        context.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "a Frame launch ticket must expire within 60 seconds",
+        });
+    }
+    validateFrameAuthority(ticket, context, "Frame launch tickets");
+});
+export const frameSessionClaimsV1Schema = z
+    .object({
+    format: z.literal("spacefast.frame-session"),
+    version: z.literal(1),
+    launchTicketId: z.string().min(16).max(512),
+    audience: frameAudienceV1Schema,
+    link: frameLinkRevisionV1Schema,
+    principal: framePrincipalV1Schema,
+    target: frameTargetV1Schema,
+    surface: z.enum(["wordpress.editor", "wordpress.preview"]),
+    parentOrigin: exactOriginSchema,
+    capabilities: z.array(grantCapabilitySchema).min(1).max(5),
+    grantDecisionDigest: contentProgramSha256Schema,
+    accessGeneration: z.number().int().nonnegative(),
+    sessionVersion: z.number().int().nonnegative(),
+    nonce: z.string().min(16).max(512),
+    issuedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().positive(),
+})
+    .strict()
+    .superRefine((claims, context) => {
+    if (claims.expiresAt <= claims.issuedAt) {
+        context.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "expiresAt must be after issuedAt",
+        });
+    }
+    if (claims.expiresAt - claims.issuedAt > 15 * 60) {
+        context.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "Frame sessions cannot live longer than 15 minutes",
+        });
+    }
+    validateFrameAuthority(claims, context, "Frame sessions");
+});