pyric 0.0.1 → 0.1.0-alpha.10

package/dist/storage/admin/api.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Pure-fetch client for the Firebase Storage provisioning APIs.
+ * Takes an OAuth access token directly — works equally from a Node
+ * agent runtime or a browser. Used by:
+ *
+ *   - `ProvisionStorageHandler` server-side via the agent SDK
+ *   - Consumers like the multi-tenant playground via direct import
+ *
+ * The caller is responsible for token scope. `firebase` scope is
+ * enough for the `:addFirebase` + `defaultLocation:finalize` calls,
+ * but **NOT** for enabling the underlying `firebasestorage.googleapis.com`
+ * service (which is the first-time gate). Service-enable requires
+ * `cloud-platform` scope OR a service account with
+ * `roles/serviceusage.serviceUsageAdmin`. Each function below
+ * documents which scope it needs.
+ *
+ * Endpoints under play:
+ *   - serviceusage.googleapis.com/v1/projects/{p}/services/{s}:enable
+ *   - firebase.googleapis.com/v1beta1/projects/{p}/defaultLocation:finalize
+ *   - firebasestorage.googleapis.com/v1beta/projects/{p}/buckets
+ *   - firebasestorage.googleapis.com/v1beta/projects/{p}/buckets/{b}:addFirebase
+ *   - firebaserules.googleapis.com/v1/projects/{p}/releases/firebase.storage
+ */
+export declare class StorageProvisioningError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly reason: string | undefined;
+    constructor(status: number, body: string, reason: string | undefined, message: string);
+}
+export type ServiceEnableState = 'enabled' | 'disabled' | 'unknown';
+/**
+ * Probe whether the `firebasestorage.googleapis.com` service is
+ * enabled on the project. Cheap, uses Service Usage `GET`. Requires
+ * `serviceusage.services.get` permission (the default Firebase Admin
+ * SDK SA has this; user OAuth tokens with `firebase` scope do not).
+ *
+ * Returns `'unknown'` on permission failures so callers can downgrade
+ * to "try the operation; observe SERVICE_DISABLED" rather than block.
+ */
+export declare function getStorageServiceState(accessToken: string, projectId: string): Promise<ServiceEnableState>;
+/**
+ * Enable `firebasestorage.googleapis.com` on the project. Requires
+ * `serviceusage.services.enable` IAM permission — included in
+ * `roles/owner`, `roles/editor` (deprecated), or
+ * `roles/serviceusage.serviceUsageAdmin`. The default Firebase Admin
+ * SDK service account does NOT have this; the caller's token must
+ * either be a user-OAuth with `cloud-platform` scope or a SA with
+ * the elevated role.
+ *
+ * Long-running operation under the hood; the response carries an
+ * operation name. We don't poll — the response 200 is enough signal
+ * for our purposes, and a brief settle delay handles propagation.
+ */
+export declare function enableStorageService(accessToken: string, projectId: string): Promise<void>;
+/**
+ * Read the project's current default GCP resources location. Returns
+ * null when the project hasn't been finalized yet — e.g. brand-new
+ * Firebase projects with no resources. `firebase` scope is sufficient.
+ */
+export declare function getDefaultLocation(accessToken: string, projectId: string): Promise<string | null>;
+/**
+ * Set the project's default GCP resources location. IRREVERSIBLE —
+ * once set, the location cannot be changed. Skip-if-set is the
+ * caller's job; this function unconditionally calls `:finalize`.
+ *
+ * Per observed behavior, `:finalize` 404s on projects that already
+ * have resources provisioned (RTDB, Hosting) without a default
+ * location. The error path surfaces that to the caller.
+ */
+export declare function finalizeDefaultLocation(accessToken: string, projectId: string, locationId: string): Promise<void>;
+export interface FirebaseStorageBucket {
+    name: string;
+    bucketId: string;
+    reconciling?: boolean;
+}
+/**
+ * List Firebase-linked Storage buckets on the project. Returns an
+ * empty list when none exist yet. Throws when the underlying service
+ * is disabled — callers should check `getStorageServiceState` first
+ * if they want to distinguish.
+ */
+export declare function listFirebaseBuckets(accessToken: string, projectId: string): Promise<FirebaseStorageBucket[]>;
+/**
+ * Link a Cloud Storage bucket to Firebase Storage. Idempotent — if
+ * the bucket is already Firebase-linked, the API returns 200 with
+ * the existing record. The bucket must already exist as a GCS
+ * resource; for the default Firebase bucket name
+ * (`{projectId}.firebasestorage.app`), Firebase auto-creates it on
+ * first `:addFirebase` call.
+ */
+export declare function addFirebaseToBucket(accessToken: string, projectId: string, bucketId: string): Promise<FirebaseStorageBucket>;
+/**
+ * Deploy a Storage rules source for a specific bucket. Firebase
+ * Storage uses **per-bucket** release names —
+ * `projects/{p}/releases/firebase.storage/{bucketId}` — for actual
+ * rule application. The project-wide `firebase.storage` release
+ * exists as a legacy alias but isn't bound to any bucket in modern
+ * projects; deploying to it leaves the bucket's deny-all rule
+ * unchanged.
+ *
+ * Defaults `bucketId` to `{projectId}.firebasestorage.app` (the
+ * Firebase default bucket name). Pass an override when targeting a
+ * non-default bucket.
+ */
+export declare function deployStorageRules(accessToken: string, projectId: string, source: string, bucketId?: string): Promise<{
+    rulesetName: string;
+}>;
+/**
+ * A single CORS rule entry, mirroring the GCS bucket CORS schema.
+ * See https://cloud.google.com/storage/docs/cross-origin#cors-elements.
+ */
+export interface CorsRule {
+    origin: string[];
+    method: string[];
+    responseHeader?: string[];
+    maxAgeSeconds?: number;
+}
+/**
+ * Default rule for a browser playground hosted on Firebase Hosting.
+ * Allows GET/POST/PUT/DELETE/HEAD/OPTIONS from the Hosting origin
+ * + common localhost dev ports, with response headers needed by the
+ * Firebase Storage Web SDK.
+ */
+export declare function defaultPlaygroundCors(hostingOrigin: string): CorsRule[];
+/** Read the current CORS configuration for a bucket. */
+export declare function getBucketCors(accessToken: string, bucketId: string): Promise<CorsRule[]>;
+/**
+ * Replace the bucket's CORS configuration. Pass an empty array to
+ * clear all rules. The GCS API replaces (not merges) the cors field
+ * on PATCH.
+ */
+export declare function setBucketCors(accessToken: string, bucketId: string, cors: CorsRule[]): Promise<void>;
+/**
+ * Step-boundary progress narration for {@link provisionStorage}. Lets a caller
+ * (the deploy CLI's status board) narrate the multi-second flow — most
+ * importantly the post-enable settle wait, which is otherwise a frozen terminal.
+ */
+export type ProvisionProgress = (event: {
+    step: string;
+    status: 'start' | 'done' | 'skip' | 'progress';
+    message: string;
+    pct?: number;
+}) => void;
+export interface ProvisionStorageOptions {
+    /**
+     * Default GCP resources location to use if the project hasn't been
+     * finalized yet. Ignored when the location is already set.
+     * Default: `'us-central'`.
+     */
+    locationId?: string;
+    /**
+     * Override the default Firebase Storage bucket ID. Defaults to
+     * `{projectId}.firebasestorage.app` — the bucket Firebase Console
+     * creates automatically.
+     */
+    bucketId?: string;
+    /**
+     * Storage rules source to deploy after the bucket is linked. When
+     * omitted, no rules are deployed (the project keeps whatever rules
+     * were last released — possibly the default deny-all).
+     */
+    rules?: string;
+    /**
+     * CORS rules to apply to the bucket after it's linked. Required
+     * for browser-side reads/writes from a non-Firebase origin —
+     * buckets created via the Cloud Console (vs Firebase Console)
+     * often ship with no CORS configuration, which manifests as
+     * `No 'Access-Control-Allow-Origin' header` on the first
+     * `XMLHttpRequest` from a hosted page.
+     *
+     * Pass `defaultPlaygroundCors(origin)` for a sensible starter
+     * config, or a custom array. Omit to leave the bucket's CORS
+     * alone.
+     */
+    cors?: CorsRule[];
+    /** Optional progress callback, invoked at each provisioning step boundary. */
+    onProgress?: ProvisionProgress;
+}
+export interface ProvisionStorageResult {
+    ok: true;
+    serviceEnabled: boolean;
+    locationFinalized: boolean;
+    locationId: string | null;
+    bucketCreated: boolean;
+    bucketId: string;
+    rulesDeployed: boolean;
+    rulesetName?: string;
+    corsApplied: boolean;
+}
+/**
+ * End-to-end Storage enablement + provisioning. Each step is
+ * idempotent (probe before mutating); the result reports what was
+ * actually done.
+ *
+ * Permission requirements (caller's token):
+ *   - `roles/serviceusage.serviceUsageAdmin` (or Owner) — to enable
+ *     the service when it's disabled
+ *   - `cloud-platform` OAuth scope (or `firebase` if service already
+ *     enabled)
+ *
+ * The handler throws `StorageProvisioningError` with the
+ * underlying `reason` (e.g. `AUTH_PERMISSION_DENIED`,
+ * `SERVICE_DISABLED`) so the caller can route to actionable UX.
+ */
+export declare function provisionStorage(accessToken: string, projectId: string, options?: ProvisionStorageOptions): Promise<ProvisionStorageResult>;
+//# sourceMappingURL=api.d.ts.map

package/dist/storage/admin/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/storage/admin/api.ts"],"names":[],"mappings":"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"}

package/dist/storage/admin/api.js

@@ -0,0 +1,349 @@
+/**
+ * Pure-fetch client for the Firebase Storage provisioning APIs.
+ * Takes an OAuth access token directly — works equally from a Node
+ * agent runtime or a browser. Used by:
+ *
+ *   - `ProvisionStorageHandler` server-side via the agent SDK
+ *   - Consumers like the multi-tenant playground via direct import
+ *
+ * The caller is responsible for token scope. `firebase` scope is
+ * enough for the `:addFirebase` + `defaultLocation:finalize` calls,
+ * but **NOT** for enabling the underlying `firebasestorage.googleapis.com`
+ * service (which is the first-time gate). Service-enable requires
+ * `cloud-platform` scope OR a service account with
+ * `roles/serviceusage.serviceUsageAdmin`. Each function below
+ * documents which scope it needs.
+ *
+ * Endpoints under play:
+ *   - serviceusage.googleapis.com/v1/projects/{p}/services/{s}:enable
+ *   - firebase.googleapis.com/v1beta1/projects/{p}/defaultLocation:finalize
+ *   - firebasestorage.googleapis.com/v1beta/projects/{p}/buckets
+ *   - firebasestorage.googleapis.com/v1beta/projects/{p}/buckets/{b}:addFirebase
+ *   - firebaserules.googleapis.com/v1/projects/{p}/releases/firebase.storage
+ */
+const SERVICEUSAGE_API = 'https://serviceusage.googleapis.com/v1';
+const FIREBASE_API = 'https://firebase.googleapis.com/v1beta1';
+const STORAGE_API = 'https://firebasestorage.googleapis.com/v1beta';
+const RULES_API = 'https://firebaserules.googleapis.com/v1';
+const GCS_API = 'https://storage.googleapis.com/storage/v1';
+const STORAGE_SERVICE = 'firebasestorage.googleapis.com';
+export class StorageProvisioningError extends Error {
+    status;
+    body;
+    reason;
+    constructor(status, body, reason, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.reason = reason;
+        this.name = 'StorageProvisioningError';
+    }
+}
+function parseError(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const reason = parsed.error?.details?.find((d) => d.reason)?.reason;
+        return {
+            reason,
+            message: parsed.error?.message ?? body.slice(0, 400),
+        };
+    }
+    catch {
+        return { reason: undefined, message: body.slice(0, 400) };
+    }
+}
+async function bearer(accessToken, url, init) {
+    const r = await fetch(url, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
+            ...(init?.headers ?? {}),
+        },
+    });
+    const body = r.ok ? '' : await r.text().catch(() => '');
+    return { status: r.status, ok: r.ok, body, response: r };
+}
+/**
+ * Probe whether the `firebasestorage.googleapis.com` service is
+ * enabled on the project. Cheap, uses Service Usage `GET`. Requires
+ * `serviceusage.services.get` permission (the default Firebase Admin
+ * SDK SA has this; user OAuth tokens with `firebase` scope do not).
+ *
+ * Returns `'unknown'` on permission failures so callers can downgrade
+ * to "try the operation; observe SERVICE_DISABLED" rather than block.
+ */
+export async function getStorageServiceState(accessToken, projectId) {
+    const r = await bearer(accessToken, `${SERVICEUSAGE_API}/projects/${encodeURIComponent(projectId)}/services/${STORAGE_SERVICE}`);
+    if (!r.ok)
+        return 'unknown';
+    const parsed = await r.response.json();
+    if (parsed.state === 'ENABLED')
+        return 'enabled';
+    if (parsed.state === 'DISABLED')
+        return 'disabled';
+    return 'unknown';
+}
+/**
+ * Enable `firebasestorage.googleapis.com` on the project. Requires
+ * `serviceusage.services.enable` IAM permission — included in
+ * `roles/owner`, `roles/editor` (deprecated), or
+ * `roles/serviceusage.serviceUsageAdmin`. The default Firebase Admin
+ * SDK service account does NOT have this; the caller's token must
+ * either be a user-OAuth with `cloud-platform` scope or a SA with
+ * the elevated role.
+ *
+ * Long-running operation under the hood; the response carries an
+ * operation name. We don't poll — the response 200 is enough signal
+ * for our purposes, and a brief settle delay handles propagation.
+ */
+export async function enableStorageService(accessToken, projectId) {
+    const r = await bearer(accessToken, `${SERVICEUSAGE_API}/projects/${encodeURIComponent(projectId)}/services/${STORAGE_SERVICE}:enable`, { method: 'POST', body: JSON.stringify({}) });
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `Failed to enable ${STORAGE_SERVICE}: ${r.status} ${message}`);
+    }
+}
+// ─── Default location ─────────────────────────────────────────────────
+/**
+ * Read the project's current default GCP resources location. Returns
+ * null when the project hasn't been finalized yet — e.g. brand-new
+ * Firebase projects with no resources. `firebase` scope is sufficient.
+ */
+export async function getDefaultLocation(accessToken, projectId) {
+    const r = await bearer(accessToken, `${FIREBASE_API}/projects/${encodeURIComponent(projectId)}`);
+    if (!r.ok) {
+        const { message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, undefined, `getProject: ${r.status} ${message}`);
+    }
+    const project = await r.response.json();
+    return project.resources?.locationId ?? null;
+}
+/**
+ * Set the project's default GCP resources location. IRREVERSIBLE —
+ * once set, the location cannot be changed. Skip-if-set is the
+ * caller's job; this function unconditionally calls `:finalize`.
+ *
+ * Per observed behavior, `:finalize` 404s on projects that already
+ * have resources provisioned (RTDB, Hosting) without a default
+ * location. The error path surfaces that to the caller.
+ */
+export async function finalizeDefaultLocation(accessToken, projectId, locationId) {
+    const r = await bearer(accessToken, `${FIREBASE_API}/projects/${encodeURIComponent(projectId)}/defaultLocation:finalize`, { method: 'POST', body: JSON.stringify({ locationId }) });
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `defaultLocation:finalize ${locationId}: ${r.status} ${message}`);
+    }
+}
+/**
+ * List Firebase-linked Storage buckets on the project. Returns an
+ * empty list when none exist yet. Throws when the underlying service
+ * is disabled — callers should check `getStorageServiceState` first
+ * if they want to distinguish.
+ */
+export async function listFirebaseBuckets(accessToken, projectId) {
+    const r = await bearer(accessToken, `${STORAGE_API}/projects/${encodeURIComponent(projectId)}/buckets`);
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `listBuckets: ${r.status} ${message}`);
+    }
+    const body = await r.response.json();
+    return (body.buckets ?? []).map((b) => ({
+        name: b.name,
+        bucketId: b.name.split('/').pop() ?? b.name,
+    }));
+}
+/**
+ * Link a Cloud Storage bucket to Firebase Storage. Idempotent — if
+ * the bucket is already Firebase-linked, the API returns 200 with
+ * the existing record. The bucket must already exist as a GCS
+ * resource; for the default Firebase bucket name
+ * (`{projectId}.firebasestorage.app`), Firebase auto-creates it on
+ * first `:addFirebase` call.
+ */
+export async function addFirebaseToBucket(accessToken, projectId, bucketId) {
+    const r = await bearer(accessToken, `${STORAGE_API}/projects/${encodeURIComponent(projectId)}/buckets/${encodeURIComponent(bucketId)}:addFirebase`, { method: 'POST', body: JSON.stringify({}) });
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `addFirebase ${bucketId}: ${r.status} ${message}`);
+    }
+    const body = await r.response.json();
+    return {
+        name: body.name ?? `projects/${projectId}/buckets/${bucketId}`,
+        bucketId,
+    };
+}
+// ─── Storage rules helpers ────────────────────────────────────────────
+/**
+ * Deploy a Storage rules source for a specific bucket. Firebase
+ * Storage uses **per-bucket** release names —
+ * `projects/{p}/releases/firebase.storage/{bucketId}` — for actual
+ * rule application. The project-wide `firebase.storage` release
+ * exists as a legacy alias but isn't bound to any bucket in modern
+ * projects; deploying to it leaves the bucket's deny-all rule
+ * unchanged.
+ *
+ * Defaults `bucketId` to `{projectId}.firebasestorage.app` (the
+ * Firebase default bucket name). Pass an override when targeting a
+ * non-default bucket.
+ */
+export async function deployStorageRules(accessToken, projectId, source, bucketId = `${projectId}.firebasestorage.app`) {
+    const headers = { 'Content-Type': 'application/json' };
+    const create = await bearer(accessToken, `${RULES_API}/projects/${encodeURIComponent(projectId)}/rulesets`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ source: { files: [{ name: 'storage.rules', content: source }] } }),
+    });
+    if (!create.ok) {
+        const { reason, message } = parseError(create.body);
+        throw new StorageProvisioningError(create.status, create.body, reason, `createRuleset: ${create.status} ${message}`);
+    }
+    const created = await create.response.json();
+    const releaseName = `projects/${projectId}/releases/firebase.storage/${bucketId}`;
+    // PATCH updates an existing release; if no release exists yet
+    // (project just had Storage enabled, no rules ever deployed),
+    // PATCH 404s. Fall back to POST `releases.create` to mint the
+    // release the first time.
+    const patch = await bearer(accessToken, `${RULES_API}/${releaseName}`, {
+        method: 'PATCH',
+        headers,
+        body: JSON.stringify({ release: { name: releaseName, rulesetName: created.name } }),
+    });
+    if (patch.ok)
+        return { rulesetName: created.name };
+    if (patch.status === 404) {
+        const createRelease = await bearer(accessToken, `${RULES_API}/projects/${encodeURIComponent(projectId)}/releases`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ name: releaseName, rulesetName: created.name }),
+        });
+        if (!createRelease.ok) {
+            const { reason, message } = parseError(createRelease.body);
+            throw new StorageProvisioningError(createRelease.status, createRelease.body, reason, `createRelease firebase.storage/${bucketId}: ${createRelease.status} ${message}`);
+        }
+        return { rulesetName: created.name };
+    }
+    const { reason, message } = parseError(patch.body);
+    throw new StorageProvisioningError(patch.status, patch.body, reason, `updateRelease firebase.storage/${bucketId}: ${patch.status} ${message}`);
+}
+/**
+ * Default rule for a browser playground hosted on Firebase Hosting.
+ * Allows GET/POST/PUT/DELETE/HEAD/OPTIONS from the Hosting origin
+ * + common localhost dev ports, with response headers needed by the
+ * Firebase Storage Web SDK.
+ */
+export function defaultPlaygroundCors(hostingOrigin) {
+    return [{
+            origin: [hostingOrigin, 'http://localhost:5173', 'http://localhost:3000', 'http://localhost:4173'],
+            method: ['GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS'],
+            responseHeader: ['Content-Type', 'Authorization', 'x-goog-meta-*', 'x-firebase-storage-version', 'x-goog-upload-*'],
+            maxAgeSeconds: 3600,
+        }];
+}
+/** Read the current CORS configuration for a bucket. */
+export async function getBucketCors(accessToken, bucketId) {
+    const r = await bearer(accessToken, `${GCS_API}/b/${encodeURIComponent(bucketId)}?fields=cors`);
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `getBucketCors ${bucketId}: ${r.status} ${message}`);
+    }
+    const body = await r.response.json();
+    return body.cors ?? [];
+}
+/**
+ * Replace the bucket's CORS configuration. Pass an empty array to
+ * clear all rules. The GCS API replaces (not merges) the cors field
+ * on PATCH.
+ */
+export async function setBucketCors(accessToken, bucketId, cors) {
+    const r = await bearer(accessToken, `${GCS_API}/b/${encodeURIComponent(bucketId)}?fields=cors`, {
+        method: 'PATCH',
+        body: JSON.stringify({ cors }),
+    });
+    if (!r.ok) {
+        const { reason, message } = parseError(r.body);
+        throw new StorageProvisioningError(r.status, r.body, reason, `setBucketCors ${bucketId}: ${r.status} ${message}`);
+    }
+}
+/**
+ * End-to-end Storage enablement + provisioning. Each step is
+ * idempotent (probe before mutating); the result reports what was
+ * actually done.
+ *
+ * Permission requirements (caller's token):
+ *   - `roles/serviceusage.serviceUsageAdmin` (or Owner) — to enable
+ *     the service when it's disabled
+ *   - `cloud-platform` OAuth scope (or `firebase` if service already
+ *     enabled)
+ *
+ * The handler throws `StorageProvisioningError` with the
+ * underlying `reason` (e.g. `AUTH_PERMISSION_DENIED`,
+ * `SERVICE_DISABLED`) so the caller can route to actionable UX.
+ */
+export async function provisionStorage(accessToken, projectId, options = {}) {
+    const locationId = options.locationId ?? 'us-central';
+    const bucketId = options.bucketId ?? `${projectId}.firebasestorage.app`;
+    const report = options.onProgress;
+    // Step 1: enable the service if needed.
+    let serviceEnabled = false;
+    const state = await getStorageServiceState(accessToken, projectId);
+    if (state !== 'enabled') {
+        report?.({ step: 'enable-service', status: 'start', message: 'enabling Storage API' });
+        await enableStorageService(accessToken, projectId);
+        serviceEnabled = true;
+        // Brief settle — service-enable is async; immediate buckets
+        // calls otherwise still 403 with SERVICE_DISABLED for a few seconds.
+        // The progress frame here is what keeps the terminal alive through the wait.
+        report?.({ step: 'settle', status: 'start', message: 'waiting for service propagation' });
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    else {
+        report?.({ step: 'enable-service', status: 'skip', message: 'Storage API already enabled' });
+    }
+    // Step 2: finalize default location if missing.
+    const existingLocation = await getDefaultLocation(accessToken, projectId);
+    let locationFinalized = false;
+    let finalLocation = existingLocation;
+    if (!existingLocation) {
+        await finalizeDefaultLocation(accessToken, projectId, locationId);
+        locationFinalized = true;
+        finalLocation = locationId;
+    }
+    // Step 3: ensure the default Firebase bucket is linked.
+    const existing = await listFirebaseBuckets(accessToken, projectId);
+    const alreadyLinked = existing.some((b) => b.bucketId === bucketId);
+    let bucketCreated = false;
+    if (!alreadyLinked) {
+        report?.({ step: 'bucket', status: 'start', message: `creating bucket ${bucketId}` });
+        await addFirebaseToBucket(accessToken, projectId, bucketId);
+        bucketCreated = true;
+    }
+    // Step 4: optionally deploy rules.
+    let rulesDeployed = false;
+    let rulesetName;
+    if (options.rules) {
+        report?.({ step: 'rules', status: 'start', message: 'deploying Storage rules' });
+        const result = await deployStorageRules(accessToken, projectId, options.rules, bucketId);
+        rulesDeployed = true;
+        rulesetName = result.rulesetName;
+    }
+    // Step 5: optionally apply CORS. Idempotent — caller passes the
+    // desired final state and we PATCH the bucket to match.
+    let corsApplied = false;
+    if (options.cors) {
+        await setBucketCors(accessToken, bucketId, options.cors);
+        corsApplied = true;
+    }
+    return {
+        ok: true,
+        serviceEnabled,
+        locationFinalized,
+        locationId: finalLocation,
+        bucketCreated,
+        bucketId,
+        rulesDeployed,
+        rulesetName,
+        corsApplied,
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/storage/admin/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/storage/admin/api.ts"],"names":[],"mappings":"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"}

package/dist/storage/admin/handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Handlers wrapping the pure-fetch `api.ts` provisioning functions
+ * with a structured outcome shape. They take a `ProjectScope`
+ * (`{ projectId, resolveToken }`) so the storage tools share the standard
+ * resolver contract with other authenticated operations.
+ *
+ * Note on permissions: `resolveToken()` typically yields a Firebase
+ * Admin SDK service-account token, which is enough for the *probe*
+ * but **insufficient for service enable** (the default SA lacks
+ * `roles/serviceusage.serviceUsageAdmin`). Agents that need to flip
+ * the service on should either grant the SA that role once, or call
+ * `provisionStorage(token, projectId)` directly with a user OAuth
+ * token that carries `cloud-platform` scope.
+ *
+ * The handler maps the underlying `StorageProvisioningError`'s
+ * `reason` field to a typed error code so callers can route to
+ * actionable UX.
+ */
+import type { ProjectScope } from '../../project-scope.js';
+import { type ProvisionProgress } from './api.js';
+import type { InspectStorageResult, ProvisionStorageInput, ProvisionStorageOutcome } from './spec.js';
+export declare class InspectStorageHandler {
+    execute(scope: ProjectScope): Promise<InspectStorageResult>;
+}
+export declare class ProvisionStorageHandler {
+    execute(scope: ProjectScope, input: ProvisionStorageInput, onProgress?: ProvisionProgress): Promise<ProvisionStorageOutcome>;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/storage/admin/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/storage/admin/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EAExB,MAAM,WAAW,CAAC;AAEnB,qBAAa,qBAAqB;IAC1B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAoBlE;AAED,qBAAa,uBAAuB;IAC5B,OAAO,CACX,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,qBAAqB,EAC5B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,uBAAuB,CAAC;CAmBpC"}