@spacefast/common 0.0.2

package/dist/contracts/device-auth.d.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+export declare const DeviceAuthorizationStartRequestSchema: z.ZodObject<{
+    clientId: z.ZodDefault<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    claim: z.ZodOptional<z.ZodObject<{
+        spaceId: z.ZodString;
+        claimToken: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DeviceAuthorizationStartRequest = z.infer<typeof DeviceAuthorizationStartRequestSchema>;
+export declare const DeviceAuthorizationStartResponseSchema: z.ZodObject<{
+    deviceCode: z.ZodString;
+    userCode: z.ZodString;
+    verificationUrl: z.ZodString;
+    interval: z.ZodNumber;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type DeviceAuthorizationStartResponse = z.infer<typeof DeviceAuthorizationStartResponseSchema>;
+export declare const DeviceAuthorizationPollRequestSchema: z.ZodObject<{
+    deviceCode: z.ZodString;
+}, z.core.$strip>;
+export type DeviceAuthorizationPollRequest = z.infer<typeof DeviceAuthorizationPollRequestSchema>;
+export declare const DeviceAuthorizationStatusSchema: z.ZodEnum<{
+    expired: "expired";
+    pending: "pending";
+    approved: "approved";
+    denied: "denied";
+    consumed: "consumed";
+}>;
+export type DeviceAuthorizationStatus = z.infer<typeof DeviceAuthorizationStatusSchema>;
+export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        expired: "expired";
+        pending: "pending";
+        approved: "approved";
+        denied: "denied";
+        consumed: "consumed";
+    }>;
+    apiKey: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        tenantId: z.ZodNullable<z.ZodString>;
+        subject: z.ZodNullable<z.ZodObject<{
+            type: z.ZodEnum<{
+                external: "external";
+                user: "user";
+                system: "system";
+                team: "team";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        ownerPrincipal: z.ZodNullable<z.ZodObject<{
+            type: z.ZodEnum<{
+                external: "external";
+                team: "team";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        createdByUserId: z.ZodString;
+        preset: z.ZodNullable<z.ZodEnum<{
+            ci_deploy: "ci_deploy";
+            space_publisher: "space_publisher";
+            space_admin: "space_admin";
+            site_admin: "site_admin";
+            domain_manager: "domain_manager";
+            team_admin: "team_admin";
+            billing_viewer: "billing_viewer";
+        }>>;
+        policy: z.ZodNullable<z.ZodObject<{
+            version: z.ZodLiteral<"2026-06-09">;
+            statements: z.ZodArray<z.ZodObject<{
+                effect: z.ZodEnum<{
+                    allow: "allow";
+                    deny: "deny";
+                }>;
+                actions: z.ZodArray<z.ZodEnum<{
+                    "*": "*";
+                    "sites:read": "sites:read";
+                    "sites:create": "sites:create";
+                    "sites:write": "sites:write";
+                    "sites:delete": "sites:delete";
+                    "sites:policy.write": "sites:policy.write";
+                    "spaces:read": "spaces:read";
+                    "spaces:create": "spaces:create";
+                    "spaces:write": "spaces:write";
+                    "spaces:delete": "spaces:delete";
+                    "spaces:publish": "spaces:publish";
+                    "spaces:transfer": "spaces:transfer";
+                    "spaces:export": "spaces:export";
+                    "spaces:import": "spaces:import";
+                    "versions:read": "versions:read";
+                    "versions:promote": "versions:promote";
+                    "versions:delete": "versions:delete";
+                    "versions:download": "versions:download";
+                    "domains:read": "domains:read";
+                    "domains:create": "domains:create";
+                    "domains:verify": "domains:verify";
+                    "domains:assign": "domains:assign";
+                    "domains:bind": "domains:bind";
+                    "domains:delete": "domains:delete";
+                    "domains:dns.write": "domains:dns.write";
+                    "domains:dns.credentials.write": "domains:dns.credentials.write";
+                    "domains:purchase": "domains:purchase";
+                    "webhooks:read": "webhooks:read";
+                    "webhooks:write": "webhooks:write";
+                    "builds:read": "builds:read";
+                    "builds:create": "builds:create";
+                    "teams:read": "teams:read";
+                    "teams:write": "teams:write";
+                    "teams:members.write": "teams:members.write";
+                    "billing:read": "billing:read";
+                    "billing:write": "billing:write";
+                    "tokens:read": "tokens:read";
+                    "tokens:create": "tokens:create";
+                    "tokens:revoke": "tokens:revoke";
+                    "mcp:tools": "mcp:tools";
+                    "runtime:manage": "runtime:manage";
+                }>>;
+                resources: z.ZodArray<z.ZodString>;
+                conditions: z.ZodOptional<z.ZodObject<{
+                    "request.client": z.ZodOptional<z.ZodEnum<{
+                        api: "api";
+                        dashboard: "dashboard";
+                        cli: "cli";
+                        worker: "worker";
+                    }>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        secretPreview: z.ZodString;
+        secret: z.ZodOptional<z.ZodString>;
+        notBefore: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        ipAllowlist: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        enabled: z.ZodBoolean;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        lastRequestAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    claimedSpaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DeviceAuthorizationPollResponse = z.infer<typeof DeviceAuthorizationPollResponseSchema>;
+export declare const DeviceAuthorizationVerifyQuerySchema: z.ZodObject<{
+    user_code: z.ZodString;
+}, z.core.$strip>;
+export type DeviceAuthorizationVerifyQuery = z.infer<typeof DeviceAuthorizationVerifyQuerySchema>;
+export declare const DeviceAuthorizationVerifyResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        expired: "expired";
+        pending: "pending";
+        approved: "approved";
+        denied: "denied";
+        consumed: "consumed";
+    }>;
+    clientId: z.ZodNullable<z.ZodString>;
+    scope: z.ZodNullable<z.ZodString>;
+    origin: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodString;
+    claim: z.ZodNullable<z.ZodObject<{
+        spaceId: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        liveUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type DeviceAuthorizationVerifyResponse = z.infer<typeof DeviceAuthorizationVerifyResponseSchema>;
+export declare const DeviceAuthorizationApproveRequestSchema: z.ZodObject<{
+    userCode: z.ZodString;
+    teamId: z.ZodString;
+    preset: z.ZodEnum<{
+        ci_deploy: "ci_deploy";
+        space_publisher: "space_publisher";
+        space_admin: "space_admin";
+        site_admin: "site_admin";
+        domain_manager: "domain_manager";
+        team_admin: "team_admin";
+        billing_viewer: "billing_viewer";
+    }>;
+}, z.core.$strict>;
+export type DeviceAuthorizationApproveRequest = z.infer<typeof DeviceAuthorizationApproveRequestSchema>;
+export declare const DeviceAuthorizationApproveResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"approved">;
+    claimedSpaceId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DeviceAuthorizationApproveResponse = z.infer<typeof DeviceAuthorizationApproveResponseSchema>;
+export declare const DeviceAuthorizationDenyRequestSchema: z.ZodObject<{
+    userCode: z.ZodString;
+}, z.core.$strip>;
+export type DeviceAuthorizationDenyRequest = z.infer<typeof DeviceAuthorizationDenyRequestSchema>;
+export declare const DeviceAuthorizationDenyResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"denied">;
+}, z.core.$strip>;
+export type DeviceAuthorizationDenyResponse = z.infer<typeof DeviceAuthorizationDenyResponseSchema>;

package/dist/contracts/device-auth.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { ApiKeyPresetSchema, ApiKeySchema } from "./api-keys.js";
+// Device authorization flow (internal-docs/platform.md Credential Bootstrap):
+// `POST /v1/auth/device` starts the flow, `POST /v1/auth/device/poll` redeems
+// it. Device codes are bearer capabilities: they ride POST bodies only, are
+// never logged, and redeem exactly once. User codes are short display codes the
+// person types on the dashboard verification page; verification attempts are
+// rate-limited per caller and per code with lockout so user codes cannot be
+// brute-forced into approving an attacker's device.
+export const DeviceAuthorizationStartRequestSchema = z
+    .object({
+    clientId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .default("spacefast-cli")
+        .describe("Requesting client identifier shown on the verification page."),
+    scope: z
+        .string()
+        .trim()
+        .min(1)
+        .max(4096)
+        .optional()
+        .describe("Requested access preset name. The approver chooses the final preset; this only seeds the verification page default."),
+    claim: z
+        .object({
+        spaceId: z
+            .string()
+            .min(1)
+            .describe("Anonymous space id being claimed with this device flow."),
+        claimToken: z
+            .string()
+            .trim()
+            .min(1)
+            .max(512)
+            .describe("Anonymous-space claim token. Stored server-side only as a hash."),
+    })
+        .strict()
+        .optional()
+        .describe("Explicit claim handoff intent. Only claim flows send this; ordinary device login leaves it absent."),
+})
+    .strict();
+export const DeviceAuthorizationStartResponseSchema = z.object({
+    deviceCode: z
+        .string()
+        .min(1)
+        .describe("High-entropy bearer capability the device polls with. Never log or display it."),
+    userCode: z
+        .string()
+        .min(1)
+        .describe("Short display code the user types on the dashboard verification page."),
+    verificationUrl: z
+        .string()
+        .url()
+        .describe("Dashboard verification page URL where the user approves this device."),
+    interval: z
+        .number()
+        .int()
+        .positive()
+        .describe("Minimum number of seconds the device must wait between polls."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which the device and user codes are no longer redeemable."),
+});
+export const DeviceAuthorizationPollRequestSchema = z.object({
+    deviceCode: z
+        .string()
+        .trim()
+        .min(1)
+        .max(512)
+        .describe("Device code returned by POST /v1/auth/device. Body-only, never a URL."),
+});
+export const DeviceAuthorizationStatusSchema = z
+    .enum(["pending", "approved", "denied", "expired", "consumed"])
+    .describe("Device authorization state. `approved` carries the one-time API key exactly once, then the record is `consumed`.");
+export const DeviceAuthorizationPollResponseSchema = z.object({
+    status: DeviceAuthorizationStatusSchema,
+    apiKey: ApiKeySchema.optional().describe("The minted API key including its one-time `secret`. Present only on the first poll after approval."),
+    claimedSpaceId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Space claimed during approval, when the device flow was started by `sf spaces claim`."),
+});
+// Verification-page surface (`GET /v1/auth/device?user_code=…`). Returns
+// requester context only — never the device code (it is the bearer capability).
+export const DeviceAuthorizationVerifyQuerySchema = z.object({
+    user_code: z
+        .string()
+        .trim()
+        .min(1)
+        .max(32)
+        .describe("User code typed by the person approving the device (dashes ignored)."),
+});
+export const DeviceAuthorizationVerifyResponseSchema = z.object({
+    status: DeviceAuthorizationStatusSchema,
+    clientId: z
+        .string()
+        .nullable()
+        .describe("Requesting client identifier recorded at device start."),
+    scope: z.string().nullable().describe("Access preset the device requested at start, if any."),
+    origin: z
+        .string()
+        .nullable()
+        .describe("Request origin (client IP) recorded when the device flow started."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which this device authorization can no longer be approved."),
+    claim: z
+        .object({
+        spaceId: z.string().describe("Anonymous space that will be claimed if approval succeeds."),
+        title: z.string().nullable().describe("Display title of the anonymous space, if available."),
+        liveUrl: z.string().nullable().describe("Current live URL of the anonymous space, if any."),
+    })
+        .strict()
+        .nullable()
+        .describe("Explicit claim handoff attached to this device authorization, if any."),
+});
+// Approval intent (`POST /v1/auth/device/approve`): the approver chooses the
+// team and preset. If the device start request carried a claim handoff, approval
+// also claims that anonymous space into the chosen team after the approval CAS
+// wins. The intent persists server-side and the poll mints from it; the chosen
+// preset's compiled policy must be a subset of the approver's effective
+// team-role policy.
+export const DeviceAuthorizationApproveRequestSchema = z
+    .object({
+    userCode: z
+        .string()
+        .trim()
+        .min(1)
+        .max(32)
+        .describe("User code shown on the device being approved (dashes ignored)."),
+    teamId: z
+        .string()
+        .min(1)
+        .describe("Team the minted API key will belong to. The approver must be a member."),
+    preset: ApiKeyPresetSchema.describe("Policy preset for the minted key. Its compiled policy must be a subset of the approver's team-role policy."),
+})
+    .strict();
+export const DeviceAuthorizationApproveResponseSchema = z
+    .object({
+    status: z.literal("approved").describe("The device authorization is approved."),
+    claimedSpaceId: z
+        .string()
+        .nullable()
+        .describe("Space claimed by the server-side claim handoff, if one was attached."),
+})
+    .strict();
+export const DeviceAuthorizationDenyRequestSchema = z.object({
+    userCode: z
+        .string()
+        .trim()
+        .min(1)
+        .max(32)
+        .describe("User code shown on the device being denied (dashes ignored)."),
+});
+export const DeviceAuthorizationDenyResponseSchema = z.object({
+    status: z.literal("denied").describe("The device authorization is denied."),
+});