@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/docs/api/tenant.md

@@ -0,0 +1,194 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / tenant
+
+# tenant
+
+## Type Aliases
+
+### TenantId
+
+```ts
+type TenantId = typeof tenantIdSchema.Type;
+```
+
+A validated host-selected tenant identity.
+
+---
+
+### TenantPrincipal
+
+```ts
+type TenantPrincipal =
+  | Readonly<{
+      actor: Extract<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+      role: "owner" | "member";
+      soleMember?: true;
+    }>
+  | Readonly<{
+      actor: Exclude<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+    }>;
+```
+
+A canonical host actor with a tenant role only when the actor is a member.
+
+---
+
+### TenantResolver
+
+```ts
+type TenantResolver = Readonly<{
+  resolve: Promise<Readonly<{
+    tenantId: TenantId;
+    origin: string;
+  }> | null>;
+}>;
+```
+
+Resolves a request before authentication; null means refuse, never fallback.
+
+---
+
+### TenantScope
+
+```ts
+type TenantScope = Readonly<{
+  tenantId: TenantId;
+  origin: string;
+  durableName: string;
+  computerName: string;
+  workspacePrefix: string;
+  repositoryPrefix: string;
+}>;
+```
+
+The only source of durable names for a standalone Oyster tenant.
+
+---
+
+### ResolvedTenant
+
+```ts
+type ResolvedTenant = Readonly<{
+  scope: TenantScope;
+  auth: OysterAuth;
+}>;
+```
+
+A host-selected scope paired with its existing authentication port.
+
+---
+
+### OysterTenancy
+
+```ts
+type OysterTenancy = Readonly<{
+  resolve: Promise<Readonly<{
+    scope: TenantScope;
+    auth: OysterAuth;
+  }> | null>;
+}>;
+```
+
+Resolve an origin-scoped host; null refuses the request without a fallback.
+
+## Variables
+
+### tenantIdSchema
+
+```ts
+const tenantIdSchema: brand<String, "OysterTenantId">;
+```
+
+A host-minted tenant slug: 2–40 lowercase ASCII letters or digits, with single
+interior hyphens. The repository separator `--` is forbidden. Hosts resolve it
+before authentication; App-controlled inputs never select it.
+
+---
+
+### defaultTenant
+
+```ts
+const defaultTenant: TenantId;
+```
+
+The single-tenant Oyster identity whose durable names remain unchanged.
+
+## Functions
+
+### tenantScope()
+
+```ts
+function tenantScope(tenantId, origin): TenantScope;
+```
+
+Name tenant-owned stores without changing any default-tenant name. The `t.`
+repository namespace cannot be a default installation slug, which forbids dots.
+Hub supplies its own Team-scoped ports and does not use this naming contract.
+
+#### Parameters
+
+| Parameter  | Type                                     |
+| ---------- | ---------------------------------------- |
+| `tenantId` | `string` & `Brand`\<`"OysterTenantId"`\> |
+| `origin`   | `string`                                 |
+
+#### Returns
+
+[`TenantScope`](#tenantscope)
+
+---
+
+### singleTenant()
+
+```ts
+function singleTenant(origin): TenantResolver;
+```
+
+Admit defaultTenant only at the configured origin. Scheme, host and port must
+match after URL canonicalization; unknown origins never fall back to default.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `origin`  | `string` |
+
+#### Returns
+
+[`TenantResolver`](#tenantresolver)
+
+---
+
+### implicitTenancy()
+
+```ts
+function implicitTenancy(origin, auth): OysterTenancy;
+```
+
+Preserve the default tenant's names and auth only at the configured origin.
+
+#### Parameters
+
+| Parameter | Type                               |
+| --------- | ---------------------------------- |
+| `origin`  | `string`                           |
+| `auth`    | [`OysterAuth`](host.md#oysterauth) |
+
+#### Returns
+
+[`OysterTenancy`](#oystertenancy)