@fungi.computer/burrow 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# Burrow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Burrow wraps Cloudflare Artifacts.
+
+`@fungi.computer/burrow` is the configured repository owner for Cloudflare
+Artifacts. Configure `createCloudflareArtifacts` with the Workers binding and a
+Publisher-owned repository metadata store at the Worker boundary. Callers
+receive stable repository identity and can request only the Git smart-HTTP
+operations used by Git: upload-pack and receive-pack advertisements and
+exchanges. The adapter persists the exact metadata returned by `create()` and
+`fork()` before later Git/head operations use the saved remote. It treats
+`get()` results as opaque method handles. Publisher stages each exact create or
+fork result and its initial token in a pending D1 record, retries revocation
+from that record, then promotes only the metadata after that exact token is no
+longer present. Pending rows do not resolve as repositories; successful
+promotion clears the token. The package never returns a token or token-bearing
+URL. A repeated fork recovers a destination only when Publisher has recorded
+that it created the fork from the exact template; an existing destination
+without that record fails closed.
+
+Cloudflare's create/fork call and the first D1 write cannot be atomic. If the
+Worker stops after the provider returns but before the pending row is committed,
+the repository can remain without recorded metadata and its initial token may
+remain active. The opaque `get()` handle cannot recover that result. The adapter
+fails closed; recovery requires a supported provider metadata recovery path or
+guarded manual cleanup outside this package.
+
+App identity and Team authorization stay with Publisher, App Release, and Hub.
+This package has no source-file API and does not decide who may use a
+repository.
+
+`readRefs(name)` returns advertised ref names and object IDs through the same
+short-lived read-token owner used by `readBranchHeads(name)`. The latter keeps
+its branch-only hash projection for source provenance checks. Both revoke the
+token on success or failure.
+
+## REST transport
+
+`createArtifactsRestNamespace({ accountId, namespace, apiToken, fetch? })`
+provides the host-only namespace where a Workers binding is unavailable. Use it
+with `createCloudflareArtifacts` and the same repository metadata store. Oyster
+uses this transport for its installation-scoped Git binding; it has no separate
+REST client. Installation permission checks remain in Oyster.
+
+REST `get(name)` only creates a name-addressed handle. `info()` and all other
+handle operations make fresh provider calls; no existence, result or authority
+is cached. The metadata owner explicitly probes lazy handles before accepting
+repository existence/readiness.
+
+The REST control-plane credential stays inside the transport. Requests refuse
+redirects and unsuccessful HTTP responses even if their envelope claims success.
+For a newly created or forked destination, the transport requires a complete
+listing with exactly one active token, revokes that token's ID, and verifies its
+revoked state before activation. Ambiguity or failed verification removes only
+that newly created destination and refuses activation. An existing-repository
+refusal never enters cleanup; a fork's source is never removed. App-facing
+repository results contain neither tokens nor authenticated URLs.
+
+REST create/fork and revocation are separate provider operations. A process
+crash between them can leave an unrecorded destination; it must fail closed on
+replay, just like an unrecorded Workers-binding creation. There is no guessed
+token-ID codec and no cleanup of another repository's tokens.
+
+## Install
+
+The packed-consumer proof verifies Burrow as an Oyster runtime dependency.
+Running the proof does not publish an npm release.
+
+The root entry exports the configured Artifacts adapter and host-only REST
+namespace. `@fungi.computer/burrow/cloudflare` also exports the Cloudflare
+adapter and its metadata-store types.
+
+## Quickstart
+
+Configure the provider namespace and metadata store at the host boundary:
+
+```ts
+import {
+  createCloudflareArtifacts,
+  type CloudflareArtifactsOptions,
+} from "@fungi.computer/burrow";
+
+export async function openRepository(options: CloudflareArtifactsOptions) {
+  const artifacts = createCloudflareArtifacts(options);
+  return artifacts.resolveRepository("notes");
+}
+```
+
+The supplied metadata store must implement the pending-record and activation
+contract described above. Repository credentials and provider remotes remain
+inside that host composition.
+
+## Packed-consumer proof
+
+After building Burrow, run `pnpm --dir packages/burrow run stranger` from the
+repository root. The maintained checker verifies the exact tarball inventory,
+installs it into a fresh npm consumer, runs local fake-provider behavior, and
+compiles both entrypoints with strict NodeNext and `skipLibCheck: false`. It
+makes no Cloudflare requests.
+
+## Examples
+
+[The local provider example](docs/home.ts) lists a repository through
+`createArtifactsRestNamespace` using a fake fetch transport. It runs without
+provider access or external credentials. After building Burrow, run it with:
+
+```sh
+pnpm exec tsx packages/burrow/docs/home.ts
+```
+
+The packed-consumer proof above also exercises repository resolution and
+read-token cleanup through the root and Cloudflare entrypoints.

package/dist/artifacts.d.ts

@@ -0,0 +1,53 @@
+/** Stable repository identity exposed to callers; no credentials or remote URL. */
+export type ArtifactsRepository = Readonly<{
+    id: string;
+    name: string;
+    defaultBranch: string;
+}>;
+/** One admitted Git smart-HTTP advertisement or byte-stream exchange. */
+export type GitExchange = Readonly<{
+    protocol?: string;
+    signal?: AbortSignal;
+}> & (Readonly<{
+    repository: string;
+    operation: "upload-pack-advertisement" | "receive-pack-advertisement";
+}> | Readonly<{
+    repository: string;
+    operation: "upload-pack" | "receive-pack";
+    body: ReadableStream<Uint8Array>;
+}>);
+/** Recorded fork identity, template main head and whether this call created it. */
+export type ArtifactsForkResult = Readonly<{
+    repository: ArtifactsRepository;
+    mainHead: string;
+    disposition: "created" | "existing";
+}>;
+/** Configured repository owner; authorization belongs to its calling host. */
+export type Artifacts = Readonly<{
+    /** Create or recover a recorded repository and finish initial-token revocation. */
+    ensureRepository(name: string): Promise<ArtifactsRepository>;
+    /** Fork the exact reviewed template main head and record its provenance. */
+    forkRepository(input: {
+        template: string;
+        repository: string;
+        expectedMainHead: string;
+    }): Promise<ArtifactsForkResult>;
+    /** Recover only a destination recorded for this exact template, or return null. */
+    recoverForkRepository(input: {
+        template: string;
+        repository: string;
+    }): Promise<ArtifactsForkResult | null>;
+    /** Resolve recorded repository identity after live existence/readiness checks. */
+    resolveRepository(name: string): Promise<ArtifactsRepository>;
+    /** Read the current main ref with a short-lived token revoked afterward. */
+    readDefaultBranchHead(name: string): Promise<string | null>;
+    /** Return advertised branch heads for revision provenance checks. */
+    readBranchHeads(name: string): Promise<readonly string[]>;
+    /** Return advertised ref names and object IDs under one short-lived read token. */
+    readRefs(name: string): Promise<readonly Readonly<{
+        name: string;
+        hash: string;
+    }>[]>;
+    /** Forward one supported Git protocol operation and revoke its token afterward. */
+    exchangeGit(input: GitExchange): Promise<Response>;
+}>;

package/dist/artifacts.js

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

package/dist/cloudflare.d.ts

@@ -0,0 +1,98 @@
+import type { Artifacts as ArtifactsApi, GitExchange } from "./artifacts.js";
+import http from "isomorphic-git/http/web";
+import type { ArtifactsRepositoryInfo } from "./namespace.js";
+/** Repository handle accepted by the Cloudflare Artifacts namespace. */
+export type CloudflareArtifactsRepositoryHandle = Readonly<{
+    /** REST handles are lazy; info resolves their live existence/readiness. */
+    info?: () => Promise<ArtifactsRepositoryInfo>;
+    /** Mint a host-only read/write token for the requested lifetime. */
+    createToken(scope: "read" | "write", ttlSeconds: number): Promise<Readonly<{
+        id: string;
+        plaintext: string;
+        expiresAt: string;
+    }>>;
+    /** Revoke this exact credential before releasing a response or activating metadata. */
+    revokeToken(tokenOrId: string): Promise<boolean>;
+    /** Fork the source main branch and return the destination initial credential. */
+    fork(name: string, options: {
+        readOnly: false;
+        defaultBranchOnly: true;
+    }): Promise<Readonly<{
+        id: string;
+        name: string;
+        remote: string;
+        defaultBranch: string;
+        token: string;
+    }>>;
+}>;
+/** Provider identity recorded at creation; used to pin later remote access. */
+export type CloudflareArtifactsRepositoryMetadata = Readonly<{
+    readonly id: string;
+    readonly name: string;
+    readonly defaultBranch: string;
+    readonly remote: string;
+    readonly parentRepository: string | null;
+}>;
+/** Host-owned durable metadata and pending initial-token revocation records. */
+export type CloudflareArtifactsRepositoryMetadataStore = Readonly<{
+    /** Read activated metadata for this repository, or null if none was recorded. */
+    read(name: string): Promise<CloudflareArtifactsRepositoryMetadata | null>;
+    /** Read the exact staged identity and initial credential awaiting revocation. */
+    readPending(name: string): Promise<Readonly<{
+        metadata: CloudflareArtifactsRepositoryMetadata;
+        initialToken: string;
+    }> | null>;
+    /** Durably stage provider identity and its initial credential before activation. */
+    recordPending(metadata: CloudflareArtifactsRepositoryMetadata, initialToken: string): Promise<void>;
+    /** Promote the staged identity after revocation and clear the pending credential. */
+    activate(metadata: CloudflareArtifactsRepositoryMetadata, initialToken: string): Promise<void>;
+}>;
+/** The maintained Cloudflare namespace methods used by this private adapter. */
+export type CloudflareArtifactsNamespace = Readonly<{
+    /** Resolve a provider repository handle or throw its typed availability error. */
+    get(name: string): Promise<CloudflareArtifactsRepositoryHandle>;
+    /** Read provider repository statuses with bounded cursor pagination. */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<CloudflareArtifactsRepositoryPage>;
+    /** Create a repository with the main branch and return its initial credential. */
+    create(name: string, options: {
+        readOnly: false;
+        setDefaultBranch: "main";
+    }): Promise<Readonly<{
+        id: string;
+        name: string;
+        remote: string;
+        defaultBranch: string;
+        token: string;
+    }>>;
+}>;
+/** Repository listing page used to observe fork/import readiness. */
+export type CloudflareArtifactsRepositoryPage = Readonly<{
+    repos: readonly Readonly<{
+        name: string;
+    }>[];
+    total: number;
+    cursor?: string;
+}>;
+/** A repository did not finish importing or forking within the readiness window. */
+export declare class ArtifactsForkStuckError extends Error {
+    readonly repository: string;
+    readonly status: "missing" | "importing" | "forking";
+    readonly name = "ArtifactsForkStuckError";
+    constructor(repository: string, status: "missing" | "importing" | "forking");
+}
+/** Execute Git with an already-held repo credential. The custody owner chooses
+ * metadata and credential; caller URLs and authorization headers never enter. */
+export declare function exchangeCloudflareArtifactsGit(metadata: CloudflareArtifactsRepositoryMetadata, input: GitExchange, credential: string, gitFetch: typeof fetch): Promise<Response>;
+/** Provider, durable metadata store and optional Git protocol transports. */
+export type CloudflareArtifactsOptions = Readonly<{
+    namespace: CloudflareArtifactsNamespace;
+    repositories: CloudflareArtifactsRepositoryMetadataStore;
+    /** Optional transport for Git protocol traffic; control remains on the namespace. */
+    gitHttp?: typeof http;
+    gitFetch?: typeof fetch;
+}>;
+/** Configure the Artifacts owner once; provider remotes and credentials stay private. */
+export declare function createCloudflareArtifacts(options: CloudflareArtifactsOptions): ArtifactsApi;