@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/tenancy/auth0.md

@@ -0,0 +1,110 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/auth0
+
+# tenancy/auth0
+
+## Type Aliases
+
+### Auth0Transaction
+
+```ts
+type Auth0Transaction = Readonly<{
+  tenantId: TenantId;
+  redirectUri: string;
+  state: string;
+  codeVerifier: string;
+  expiresAt: number;
+}>;
+```
+
+One short-lived, single-use browser authorization transaction.
+
+---
+
+### Auth0Session
+
+```ts
+type Auth0Session = Readonly<{
+  tenantId: TenantId;
+  identity: Identity;
+  expiresAt: number;
+}>;
+```
+
+Server-owned verified identity session; browsers receive only its random handle.
+
+---
+
+### Auth0BrowserOptions
+
+```ts
+type Auth0BrowserOptions = Readonly<{
+  callbackPath: string;
+  resolveTenant: ReadonlyTenancy["resolve"];
+  registry: Pick<ReadonlyTenantRegistry, "get" | "membershipOf">;
+  transactions: Readonly<{
+    put: Promise<void>;
+    take: Promise<Readonly<{
+      tenantId: TenantId;
+      redirectUri: string;
+      state: string;
+      codeVerifier: string;
+      expiresAt: number;
+    }> | null>;
+  }>;
+  sessions: Readonly<{
+    put: Promise<void>;
+    get: Promise<Readonly<{
+      tenantId: TenantId;
+      identity: Identity;
+      expiresAt: number;
+    }> | null>;
+  }>;
+}>;
+```
+
+Host ports for optional browser login; stored state must be shared across host
+instances.
+
+---
+
+### Auth0Options
+
+```ts
+type Auth0Options = Readonly<{
+  domain: string;
+  clientId: string;
+  audience: string;
+  clientSecret?: string;
+  fetch?: typeof globalThis.fetch;
+  browser?: Auth0BrowserOptions;
+}>;
+```
+
+Auth0 issuer and audience configuration; browser login is opt-in.
+
+## Functions
+
+### auth0()
+
+```ts
+function auth0(options): AuthAdapter;
+```
+
+Verify Auth0 identities; the registry alone supplies canonical membership and
+role.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `options` | [`Auth0Options`](#auth0options) |
+
+#### Returns
+
+[`AuthAdapter`](../tenancy.md#authadapter)

package/docs/api/tenancy/cloudflare.md

@@ -0,0 +1,221 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/cloudflare
+
+# tenancy/cloudflare
+
+## Type Aliases
+
+### RateLimitOptions
+
+```ts
+type RateLimitOptions = Readonly<{
+  retryAfterSeconds: number;
+}>;
+```
+
+Retry-After is an advisory response delay, not a configured quota or reset time.
+
+---
+
+### RegistryAdmission
+
+```ts
+type RegistryAdmission = Readonly<{
+  tenant: Tenant;
+  membership: Membership | null;
+}>;
+```
+
+The registry owner's atomic read of one host and one identity.
+
+---
+
+### AdmissionRecord
+
+```ts
+type AdmissionRecord = RegistryAdmission &
+  Readonly<{
+    host: string;
+    identity: Identity;
+  }>;
+```
+
+One request's atomic registry read, with the host and identity it named.
+
+---
+
+### TenantAdmission
+
+```ts
+type TenantAdmission = AdmissionRecord & Brand<"TenantAdmission">;
+```
+
+One atomic registry read for one request. Only
+[durableObjectRegistry](#durableobjectregistry) constructs it, so lower layers
+cannot mint authority.
+
+---
+
+### TenancyRegistryDO
+
+```ts
+type TenancyRegistryDO = ManagedTenantRegistry &
+  Required<Pick<ReadonlyTenantRegistry, "byDomain">> &
+  Readonly<{
+    admission: Promise<Readonly<{
+      tenant: Tenant;
+      membership: Membership | null;
+    }> | null>;
+  }> &
+  Rpc.DurableObjectBranded;
+```
+
+Native registry instance; its public shape exposes no runtime-private state.
+
+---
+
+### DomainRegistry
+
+```ts
+type DomainRegistry = ReadonlyTenantRegistry &
+  Required<Pick<ReadonlyTenantRegistry, "byDomain">>;
+```
+
+A read-only registry that includes the provisioned-domain index.
+
+---
+
+### DurableReadonlyRegistry
+
+```ts
+type DurableReadonlyRegistry = DomainRegistry &
+  Readonly<{
+    admission: Promise<TenantAdmission | null>;
+  }>;
+```
+
+Read-only native registry, with one-read request admission.
+
+---
+
+### DurableRegistry
+
+```ts
+type DurableRegistry = ManagedTenantRegistry & DurableReadonlyRegistry;
+```
+
+Managed native registry includes the provisioned-domain index.
+
+## Variables
+
+### TenancyRegistryDO
+
+```ts
+TenancyRegistryDO: (ctx) => TenancyRegistryDO;
+```
+
+Re-export from a host Worker and bind a SQLite-backed Durable Object namespace.
+
+Re-export from a host Worker and bind a SQLite-backed Durable Object namespace.
+
+#### Parameters
+
+| Parameter | Type                 |
+| --------- | -------------------- |
+| `ctx`     | `DurableObjectState` |
+
+#### Returns
+
+[`TenancyRegistryDO`](#tenancyregistrydo-1)
+
+## Functions
+
+### rateLimit()
+
+```ts
+function rateLimit(binding, options): TenancyPolicy;
+```
+
+Delegate abuse admission to the configured native binding, using only its key
+API.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `binding` | `Pick`\<`RateLimit`, `"limit"`\>        |
+| `options` | [`RateLimitOptions`](#ratelimitoptions) |
+
+#### Returns
+
+[`TenancyPolicy`](../tenancy.md#tenancypolicy)
+
+---
+
+### durableObjectRegistry()
+
+#### Call Signature
+
+```ts
+function durableObjectRegistry(binding, options): DurableReadonlyRegistry;
+```
+
+Explicitly expose only read methods when the host requests a read-only facade.
+
+##### Parameters
+
+| Parameter          | Type                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| `binding`          | `Pick`\<`DurableObjectNamespace`\<[`TenancyRegistryDO`](#tenancyregistrydo-1)\>, `"getByName"`\> |
+| `options`          | \{ `readonly`: `true`; \}                                                                        |
+| `options.readonly` | `true`                                                                                           |
+
+##### Returns
+
+[`DurableReadonlyRegistry`](#durablereadonlyregistry)
+
+#### Call Signature
+
+```ts
+function durableObjectRegistry(binding, options?): DurableRegistry;
+```
+
+Use one namespace's registry object as the tenant and owner mapping authority.
+
+##### Parameters
+
+| Parameter           | Type                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| `binding`           | `Pick`\<`DurableObjectNamespace`\<[`TenancyRegistryDO`](#tenancyregistrydo-1)\>, `"getByName"`\> |
+| `options?`          | \{ `readonly?`: `false`; \}                                                                      |
+| `options.readonly?` | `false`                                                                                          |
+
+##### Returns
+
+[`DurableRegistry`](#durableregistry)
+
+---
+
+### admittedRegistry()
+
+```ts
+function admittedRegistry(admission): DomainRegistry;
+```
+
+Answer registry reads only from one request's admission. Any other tenant, host,
+identity or member reads as absent, so every refusal stays closed.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `admission` | [`TenantAdmission`](#tenantadmission) |
+
+#### Returns
+
+[`DomainRegistry`](#domainregistry)

package/docs/api/tenancy/cold-directory.md

@@ -0,0 +1,46 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/cold-directory
+
+# tenancy/cold-directory
+
+## Type Aliases
+
+### ColdTenantDirectory
+
+```ts
+type ColdTenantDirectory = Readonly<{
+  resolve: Promise<Readonly<{
+    scope: TenantScope;
+    auth: OysterAuth;
+  }> | null>;
+}>;
+```
+
+Live directory admission for a host-persisted tenant during background work.
+
+## Functions
+
+### coldTenantDirectory()
+
+```ts
+function coldTenantDirectory(registry): ColdTenantDirectory;
+```
+
+Reconstruct background admission from the same host-owned tenant registry. Every
+selection and member lookup reads current authority. This adapter has no
+credential authority: its authenticate method always refuses requests.
+
+#### Parameters
+
+| Parameter  | Type                                                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| `registry` | `Pick`\<[`ReadonlyTenantRegistry`](../tenancy.md#readonlytenantregistry), `"get"` \| `"status"` \| `"memberById"`\> |
+
+#### Returns
+
+[`ColdTenantDirectory`](#coldtenantdirectory)

package/docs/api/tenancy/owner-key.md

@@ -0,0 +1,63 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/owner-key
+
+# tenancy/owner-key
+
+## Type Aliases
+
+### OwnerKeyRecord
+
+```ts
+type OwnerKeyRecord = Readonly<{
+  key: string;
+  memberId: string;
+}>;
+```
+
+Stored owner verification material for one selected tenant.
+
+---
+
+### OwnerKeyOptions
+
+```ts
+type OwnerKeyOptions = Readonly<{
+  registry: Pick<ReadonlyTenantRegistry, "get">;
+  keys: Readonly<{
+    get: Promise<Readonly<{
+      key: string;
+      memberId: string;
+    }> | null>;
+  }>;
+  login?: Readonly<{
+    resolveTenant: ReadonlyTenancy["resolve"];
+  }>;
+}>;
+```
+
+Live owner authority and host-held verification material.
+
+## Functions
+
+### ownerKey()
+
+```ts
+function ownerKey(options): AuthAdapter;
+```
+
+Reuse Oyster verification and admit only a current, explicitly stored owner.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `options` | [`OwnerKeyOptions`](#ownerkeyoptions) |
+
+#### Returns
+
+[`AuthAdapter`](../tenancy.md#authadapter)

package/docs/api/tenancy/registry.md

@@ -0,0 +1,77 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/registry
+
+# tenancy/registry
+
+## Type Aliases
+
+### MemoryMembership
+
+```ts
+type MemoryMembership = Readonly<{
+  tenantId: TenantId;
+  identity: Identity;
+  memberId: string;
+  role: Membership["role"];
+}>;
+```
+
+Initial live membership records for a disposable in-memory registry.
+
+---
+
+### MemoryRegistryOptions
+
+```ts
+type MemoryRegistryOptions = Readonly<{
+  tenants?: readonly Tenant[];
+  memberships?: readonly MemoryMembership[];
+}>;
+```
+
+Provisioned records and canonical member mappings owned by the host.
+
+---
+
+### MemoryRegistry
+
+```ts
+type MemoryRegistry = ManagedTenantRegistry &
+  Readonly<{
+    byDomain: Promise<Readonly<{
+      id: TenantId;
+      handle: string;
+      origin: string;
+      status: "active" | "suspended" | "deleting";
+      owners: readonly string[];
+      domains: readonly string[];
+    }> | null>;
+  }>;
+```
+
+The memory adapter always supplies the optional custom-domain index.
+
+## Functions
+
+### memoryRegistry()
+
+```ts
+function memoryRegistry(options?): MemoryRegistry;
+```
+
+In-memory tenant and member owner; create updates both atomically.
+
+#### Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `options` | [`MemoryRegistryOptions`](#memoryregistryoptions) |
+
+#### Returns
+
+[`MemoryRegistry`](#memoryregistry)

package/docs/api/tenancy/resolve.md

@@ -0,0 +1,69 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/resolve
+
+# tenancy/resolve
+
+## Functions
+
+### subdomain()
+
+```ts
+function subdomain(baseDomain): TenantResolverAdapter<"origin">;
+```
+
+Resolve a provisioned label immediately below a configured base hostname.
+
+#### Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `baseDomain` | `string` |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"origin"`\>
+
+---
+
+### hosts()
+
+```ts
+function hosts(registry): TenantResolverAdapter<"origin">;
+```
+
+Resolve a provisioned custom domain through the registry's domain index.
+
+#### Parameters
+
+| Parameter  | Type                                                             |
+| ---------- | ---------------------------------------------------------------- |
+| `registry` | [`ReadonlyTenantRegistry`](../tenancy.md#readonlytenantregistry) |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"origin"`\>
+
+---
+
+### path()
+
+```ts
+function path(pattern): TenantResolverAdapter<"path">;
+```
+
+Resolve provisioned path tenants for APIs; this resolver cannot host Oyster.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `pattern` | `string` |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"path"`\>