@spacefast/common 0.0.2

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/access-policy.d.ts

@@ -0,0 +1,39 @@
+import { type ApiKeyPreset, type StatticAccessPolicy, type StatticAction } from "../contracts/api-keys.js";
+type RequestCondition = NonNullable<StatticAccessPolicy["statements"][number]["conditions"]>;
+export type PolicyCompileInput = {
+    tenantId: string;
+    teamId: string;
+};
+export type PolicyAuthorizeInput = {
+    policy: StatticAccessPolicy;
+    action: StatticAction;
+    /**
+     * Candidate resource URIs for one request target, evaluated together: spaces
+     * are addressed by their canonical site-rooted URI AND a principal-scoped
+     * candidate so principal wildcards cover them. A deny matching ANY candidate
+     * wins; otherwise an allow matching any candidate permits.
+     */
+    resource: string | readonly string[];
+    conditions?: RequestCondition;
+};
+export declare function compileApiKeyPreset(preset: ApiKeyPreset, input: PolicyCompileInput): StatticAccessPolicy;
+export declare function compileTeamRolePolicy(input: PolicyCompileInput & {
+    role: string;
+}): StatticAccessPolicy;
+export declare function allowPolicy(actions: StatticAction[], resources: string[]): StatticAccessPolicy;
+export declare function denyAllPolicy(): StatticAccessPolicy;
+export declare function policyIsSubsetOfGrantor(requested: StatticAccessPolicy, grantor: StatticAccessPolicy): boolean;
+export declare function policyAllows(input: PolicyAuthorizeInput): boolean;
+export declare function grantedTenantsFromPolicy(policy: StatticAccessPolicy): {
+    all: boolean;
+    tenantIds: string[];
+};
+export declare function grantedPrincipalsFromPolicy(policy: StatticAccessPolicy, input: {
+    tenantId: string;
+    principalType: "team" | "external";
+}): {
+    all: boolean;
+    principalIds: string[];
+};
+export declare function policyReaches(policy: StatticAccessPolicy, resourceBase: string): boolean;
+export {};

package/dist/utils/access-policy.js

@@ -0,0 +1,232 @@
+import { SPACEFAST_ACCESS_POLICY_VERSION, parseStatticResource, } from "../contracts/api-keys.js";
+const publishActions = [
+    "spaces:read",
+    "spaces:create",
+    "spaces:write",
+    "spaces:publish",
+    "versions:read",
+    "versions:promote",
+    "versions:download",
+    "builds:read",
+    "builds:create",
+];
+const spaceAdminActions = [
+    ...publishActions,
+    "spaces:delete",
+    "spaces:transfer",
+    "spaces:export",
+    "spaces:import",
+    "versions:delete",
+    // Resolving the owning team (name/slug) is part of administering its spaces:
+    // the CLI resolves teams before every publish, so admin-tier presets carry
+    // read access to the team resource itself.
+    "teams:read",
+];
+const domainActions = [
+    "domains:read",
+    "domains:create",
+    "domains:verify",
+    "domains:assign",
+    "domains:bind",
+    "domains:delete",
+    "domains:dns.write",
+    "domains:purchase",
+];
+function teamResource(input) {
+    return `stt://tenant/${input.tenantId}/principal/team/${input.teamId}/*`;
+}
+export function compileApiKeyPreset(preset, input) {
+    const resource = teamResource(input);
+    switch (preset) {
+        case "ci_deploy":
+        case "space_publisher":
+            return allowPolicy(publishActions, [resource]);
+        case "space_admin":
+            return allowPolicy(spaceAdminActions, [resource]);
+        case "site_admin":
+            return allowPolicy([
+                "sites:read",
+                "sites:create",
+                "sites:write",
+                "sites:delete",
+                "sites:policy.write",
+                ...spaceAdminActions,
+                ...domainActions,
+                "webhooks:read",
+                "webhooks:write",
+            ], [resource]);
+        case "domain_manager":
+            return allowPolicy(domainActions, [resource]);
+        case "billing_viewer":
+            return allowPolicy(["teams:read", "billing:read"], [resource]);
+        case "team_admin":
+            return allowPolicy(["*"], [resource]);
+    }
+}
+export function compileTeamRolePolicy(input) {
+    switch (input.role) {
+        case "owner":
+        case "admin":
+            return compileApiKeyPreset("team_admin", input);
+        case "member":
+            return allowPolicy([
+                "sites:read",
+                "spaces:read",
+                "spaces:create",
+                "spaces:write",
+                "spaces:publish",
+                "versions:read",
+                "versions:promote",
+                "versions:download",
+                "domains:read",
+                "builds:read",
+                "builds:create",
+                "teams:read",
+                "billing:read",
+            ], [teamResource(input)]);
+        default:
+            return denyAllPolicy();
+    }
+}
+export function allowPolicy(actions, resources) {
+    return {
+        version: SPACEFAST_ACCESS_POLICY_VERSION,
+        statements: [{ effect: "allow", actions: [...new Set(actions)], resources }],
+    };
+}
+export function denyAllPolicy() {
+    return {
+        version: SPACEFAST_ACCESS_POLICY_VERSION,
+        statements: [{ effect: "deny", actions: ["*"], resources: ["stt://tenant/*"] }],
+    };
+}
+export function policyIsSubsetOfGrantor(requested, grantor) {
+    return (requested.statements.every((statement) => {
+        if (statement.effect === "deny") {
+            return true;
+        }
+        return statement.actions.every((action) => statement.resources.every((resource) => grantorAllows(grantor, action, resource, statement.conditions)));
+    }) && grantorDeniesArePreserved(requested, grantor));
+}
+// Request-time evaluation (internal-docs/platform.md IAM-lite): explicit deny wins,
+// explicit allow permits, otherwise implicit deny. Condition keys are ANDed and an
+// unresolvable condition attribute fails closed (see `conditionsMatch`).
+export function policyAllows(input) {
+    const resources = typeof input.resource === "string" ? [input.resource] : input.resource;
+    if (resources.some((resource) => matchesEffect(input.policy, "deny", input.action, resource, input.conditions, "request"))) {
+        return false;
+    }
+    return resources.some((resource) => matchesEffect(input.policy, "allow", input.action, resource, input.conditions, "request"));
+}
+// The tenants a credential's policy grants any access to. Drives tenant
+// selection (internal-docs/platform.md Tenant): `X-Spacefast-Tenant-Id` may pick
+// one granted tenant but is never an authority by itself, and a token spanning
+// multiple tenants must fail ambiguous requests with `tenant_selection_required`.
+export function grantedTenantsFromPolicy(policy) {
+    const tenantIds = new Set();
+    let all = false;
+    for (const statement of policy.statements) {
+        if (statement.effect !== "allow") {
+            continue;
+        }
+        for (const resource of statement.resources) {
+            const tenantId = parseStatticResource(resource)?.tenantId;
+            if (tenantId === "*") {
+                all = true;
+            }
+            else if (tenantId !== undefined) {
+                tenantIds.add(tenantId);
+            }
+        }
+    }
+    return { all, tenantIds: [...tenantIds] };
+}
+// The principal ids of one type a policy grants any access to within a tenant.
+// Used to scope list queries; specific actions still go through `policyAllows`.
+export function grantedPrincipalsFromPolicy(policy, input) {
+    const principalIds = new Set();
+    let all = false;
+    for (const statement of policy.statements) {
+        if (statement.effect !== "allow") {
+            continue;
+        }
+        for (const resource of statement.resources) {
+            const parsed = parseStatticResource(resource);
+            if (!parsed || (parsed.tenantId !== input.tenantId && parsed.tenantId !== "*")) {
+                continue;
+            }
+            // Tenant-rooted grants (both `stt://tenant/*` and a concrete
+            // `stt://tenant/{t}` already filtered to this tenant) are scope-wide:
+            // they reach every principal in the tenant.
+            if (parsed.kind === "tenant") {
+                all = true;
+            }
+            else if (parsed.kind === "principal" && parsed.principalType === input.principalType) {
+                if (parsed.principalId === "*") {
+                    all = true;
+                }
+                else {
+                    principalIds.add(parsed.principalId);
+                }
+            }
+        }
+    }
+    return { all, principalIds: [...principalIds] };
+}
+// Whether the policy's allow statements reach a resource subtree at all —
+// either a statement resource covers the base, or it lives inside the base.
+// This is a visibility/scoping check (404 vs 403), never an action grant.
+export function policyReaches(policy, resourceBase) {
+    return policy.statements.some((statement) => statement.effect === "allow" &&
+        statement.resources.some((resource) => resourceMatches(resource, resourceBase) ||
+            resource === resourceBase ||
+            resource.startsWith(`${resourceBase}/`)));
+}
+function grantorAllows(policy, action, resource, conditions) {
+    if (matchesEffect(policy, "deny", action, resource, conditions, "subset")) {
+        return false;
+    }
+    return matchesEffect(policy, "allow", action, resource, conditions, "subset");
+}
+function grantorDeniesArePreserved(requested, grantor) {
+    return grantor.statements
+        .filter((statement) => statement.effect === "deny")
+        .every((deny) => deny.actions.every((action) => deny.resources.every((resource) => matchesEffect(requested, "deny", action, resource, deny.conditions, "subset"))));
+}
+function matchesEffect(policy, effect, action, resource, conditions, mode) {
+    return policy.statements.some((statement) => statement.effect === effect &&
+        statement.actions.some((candidate) => candidate === "*" || candidate === action) &&
+        statement.resources.some((candidate) => resourceMatches(candidate, resource)) &&
+        conditionsMatch(statement.conditions, conditions, effect, mode));
+}
+function resourceMatches(pattern, resource) {
+    if (pattern === resource) {
+        return true;
+    }
+    if (pattern.endsWith("/*")) {
+        return resource === pattern.slice(0, -2) || resource.startsWith(pattern.slice(0, -1));
+    }
+    // A tenant-rooted resource is scope-wide (internal-docs/platform.md L617/L879:
+    // `stt://tenant/{t}` is a grantable StatticResource and resource grants cover
+    // their subtree): it covers every resource inside that tenant. This is the
+    // tenant-scoped (partner/agency) credential shape.
+    if (parseStatticResource(pattern)?.kind === "tenant") {
+        return resource.startsWith(`${pattern}/`);
+    }
+    return false;
+}
+function conditionsMatch(statementConditions, contextConditions, effect, mode) {
+    if (!statementConditions) {
+        return true;
+    }
+    return Object.entries(statementConditions).every(([key, value]) => {
+        const resolved = contextConditions?.[key];
+        if (resolved === undefined && mode === "request") {
+            // Fail closed on unresolvable condition attributes: the condition never
+            // matches for allow statements and always matches for deny statements, so
+            // callers cannot dodge a deny by stripping request context.
+            return effect === "deny";
+        }
+        return resolved === value;
+    });
+}

package/dist/utils/api.d.ts

@@ -0,0 +1,4 @@
+export type UnwrapEnvelope<B> = B extends {
+    data: infer D;
+} ? Exclude<keyof B, "data" | "$schema"> extends never ? D : B : B;
+export declare function unwrapEnvelope<B>(body: B): UnwrapEnvelope<B>;

package/dist/utils/api.js

@@ -0,0 +1,13 @@
+// Response envelope helpers for the CLI's HTTP layer. The canonical client
+// implementation lives in @spacefast/sdk (generated from the external OpenAPI
+// spec); browser surfaces import the SDK directly via app-shell/lib/api.ts.
+export function unwrapEnvelope(body) {
+    if (body &&
+        typeof body === "object" &&
+        !Array.isArray(body) &&
+        "data" in body &&
+        Object.keys(body).every((key) => key === "data" || key === "$schema")) {
+        return body.data;
+    }
+    return body;
+}

package/dist/utils/auth-redirect.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeDashboardReturnTo(returnTo: string | null | undefined): string | undefined;

package/dist/utils/auth-redirect.js

@@ -0,0 +1,48 @@
+const INVALID_RETURN_TO_PREFIXES = ["/login", "/log-in", "/sign-in"];
+const DASHBOARD_RETURN_TO_BASE = "https://dashboard.local";
+function decodedReturnTo(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function hasUnsafeReturnToChars(value) {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (char === "\\" || code < 0x20 || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+export function sanitizeDashboardReturnTo(returnTo) {
+    const normalized = returnTo?.trim();
+    const decoded = normalized ? decodedReturnTo(normalized) : null;
+    if (!normalized ||
+        !decoded ||
+        !normalized.startsWith("/") ||
+        normalized.startsWith("//") ||
+        decoded.startsWith("//") ||
+        hasUnsafeReturnToChars(normalized) ||
+        hasUnsafeReturnToChars(decoded)) {
+        return undefined;
+    }
+    let url;
+    try {
+        url = new URL(normalized, DASHBOARD_RETURN_TO_BASE);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.origin !== DASHBOARD_RETURN_TO_BASE) {
+        return undefined;
+    }
+    const safePath = `${url.pathname}${url.search}${url.hash}`;
+    const lowerPath = url.pathname.toLowerCase();
+    if (INVALID_RETURN_TO_PREFIXES.some((prefix) => lowerPath === prefix || lowerPath.startsWith(`${prefix}/`))) {
+        return undefined;
+    }
+    return safePath;
+}

package/dist/utils/auth.d.ts

@@ -0,0 +1,5 @@
+export declare const SPACEFAST_TENANT_HEADER = "x-spacefast-tenant-id";
+export declare const SPACEFAST_CLIENT_HEADER = "x-spacefast-client";
+export declare const SPACEFAST_CLI_DEVICE_CLIENT_ID = "spacefast-cli";
+export declare function normalizeDeviceUserCode(value: string): string;
+export declare function formatDeviceUserCode(value: string): string;

package/dist/utils/auth.js

@@ -0,0 +1,13 @@
+export const SPACEFAST_TENANT_HEADER = "x-spacefast-tenant-id";
+export const SPACEFAST_CLIENT_HEADER = "x-spacefast-client";
+export const SPACEFAST_CLI_DEVICE_CLIENT_ID = "spacefast-cli";
+export function normalizeDeviceUserCode(value) {
+    return value.replace(/[^a-z0-9]/gi, "").toUpperCase();
+}
+export function formatDeviceUserCode(value) {
+    const normalized = normalizeDeviceUserCode(value).slice(0, 8);
+    if (normalized.length <= 4) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 4)}-${normalized.slice(4)}`;
+}

package/dist/utils/build-settings.d.ts

@@ -0,0 +1,49 @@
+export type BuildSettingsInput = {
+    fileNames: Iterable<string>;
+    packageJson?: string | null | undefined;
+    vercelJson?: string | null | undefined;
+    netlifyToml?: string | null | undefined;
+    wranglerToml?: string | null | undefined;
+    wranglerJson?: string | null | undefined;
+    rootDirectory?: string | null | undefined;
+};
+export type DetectedBuildSettings = {
+    frameworkPreset: string | null;
+    installCommand: string | null;
+    buildCommand: string | null;
+    outputDirectory: string | null;
+    rootDirectory: string | null;
+    platformPreset: string | null;
+    detectedFiles: string[];
+};
+export declare const BUILD_ANALYZER_CANDIDATE_ROOTS: readonly ["apps", "packages", "sites", "docs"];
+export type BuildAnalyzerCandidateRankInput = {
+    detected: Pick<DetectedBuildSettings, "platformPreset" | "frameworkPreset" | "buildCommand">;
+    rootDirectory: string | null;
+    fileNames: Iterable<string>;
+};
+export declare function hasWorkspaceSignal(fileNames: Iterable<string>, packageJsonText?: string | null): unknown;
+export declare function rankBuildAnalyzerCandidate(input: BuildAnalyzerCandidateRankInput): {
+    confidence: number;
+    reasons: string[];
+};
+export declare function hasBuildAnalyzerCandidateSignal(input: {
+    detected: Pick<DetectedBuildSettings, "detectedFiles" | "platformPreset" | "frameworkPreset" | "buildCommand">;
+    fileNames: Iterable<string>;
+}): boolean;
+export type PlatformConfig = {
+    platform: "vercel" | "netlify" | "cloudflare-pages";
+    rootDirectory: string | null;
+    installDirectory: string | null;
+    installCommand: string | null;
+    buildCommand: string | null;
+    outputDirectory: string | null;
+    redirects: Array<Record<string, unknown>>;
+    rewrites: Array<Record<string, unknown>>;
+    headers: Array<Record<string, unknown>>;
+    unsupportedFeatures: string[];
+};
+export declare function stringField(value: Record<string, unknown> | null, key: string): string | null;
+export declare function numberField(value: Record<string, unknown> | null, key: string): number | null;
+export declare function detectPlatformConfigs(input: Omit<BuildSettingsInput, "fileNames" | "packageJson">): PlatformConfig[];
+export declare function detectBuildSettings(input: BuildSettingsInput): DetectedBuildSettings;