@lanes-sh/link 0.1.0

package/src/deployments/adapters/otlp.ts

@@ -0,0 +1,128 @@
+import type { AuditDraft, AuditEvent, AuditSink } from '#audit';
+import type { FetchLike } from './gcs.ts';
+
+/**
+ * The log to an OpenTelemetry collector, over OTLP/HTTP with a JSON body.
+ *
+ * `fetch` and a shape, rather than `@opentelemetry/*`. The SDK brings a
+ * provider, a processor, an exporter and a resource detector to solve batching
+ * and context propagation — neither of which applies here: there is one record
+ * type, it is already complete when it arrives, and there is no span to
+ * correlate it with. A repository that enforces a seven-day release-age floor
+ * on dependencies because it holds live refresh tokens does not add a
+ * transitive tree to build one JSON object.
+ *
+ * JSON rather than protobuf for the same reason — protobuf would be the whole
+ * of the dependency. Every collector that accepts OTLP/HTTP accepts
+ * `application/json`; the spec requires it.
+ *
+ * **Never the primary sink.** This is a copy, and `fanOutAudit` is what keeps
+ * that true: a collector being down must not fail a capability call, and the
+ * durable log is somewhere that does not need a network.
+ */
+
+/** OTel severity numbers. The spec's scale, not an invention. */
+const SEVERITY_INFO = 9;
+const SEVERITY_WARN = 13;
+const SEVERITY_ERROR = 17;
+
+export interface OtlpAuditOptions {
+  /** The logs endpoint, e.g. `https://collector.example/v1/logs`. */
+  readonly endpoint: string;
+  /** Static headers — an API key, a tenant id. Resolved from a credential ref by the caller. */
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly serviceName?: string;
+  readonly now?: () => Date;
+  readonly fetch?: FetchLike;
+  /** Abandon a send after this long, so a hung collector cannot pile up copies. */
+  readonly timeoutMs?: number;
+}
+
+export function createOtlpAuditSink(options: OtlpAuditOptions): AuditSink {
+  const call = options.fetch ?? globalThis.fetch;
+  const now = options.now ?? ((): Date => new Date());
+  const serviceName = options.serviceName ?? 'lanes-link';
+  const timeoutMs = options.timeoutMs ?? 5000;
+
+  return {
+    async append(draft: AuditDraft): Promise<AuditEvent> {
+      const event: AuditEvent = { ...draft, id: `evt_${crypto.randomUUID()}`, timestamp: now() };
+
+      const response = await call(options.endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...options.headers },
+        body: JSON.stringify(payload(event, serviceName)),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+
+      // Raised so the fan-out can report it once. It never reaches a caller.
+      if (!response.ok) {
+        const detail = (await response.text().catch(() => '')).slice(0, 200);
+        throw new Error(`OTLP collector answered ${response.status}. ${detail}`);
+      }
+      return event;
+    },
+
+    async close(): Promise<void> {},
+  };
+}
+
+function payload(event: AuditEvent, serviceName: string): unknown {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: [stringAttribute('service.name', serviceName)] },
+        scopeLogs: [
+          {
+            scope: { name: 'lanes-link/audit' },
+            logRecords: [logRecord(event)],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function logRecord(event: AuditEvent): unknown {
+  return {
+    // Nanoseconds as a string: the spec's type is fixed64, and a millisecond
+    // timestamp times a million is past 2^53 — JSON's number would round it.
+    timeUnixNano: `${BigInt(event.timestamp.getTime()) * 1_000_000n}`,
+    severityNumber: severityOf(event),
+    severityText: severityTextOf(event),
+    // The capability, so a collector's default view is a list of what was
+    // attempted rather than a column of identical strings.
+    body: { stringValue: event.capability },
+    attributes: [
+      stringAttribute('lanes.profile', event.profile),
+      stringAttribute('lanes.principal', event.principal),
+      stringAttribute('lanes.provider', event.provider),
+      stringAttribute('lanes.authorization', event.authorization),
+      stringAttribute('lanes.status', event.status),
+      stringAttribute('lanes.event_id', event.id),
+      { key: 'lanes.duration_ms', value: { intValue: String(event.durationMs) } },
+      ...(event.connection ? [stringAttribute('lanes.connection', event.connection)] : []),
+      ...(event.clientLabel ? [stringAttribute('lanes.client', event.clientLabel)] : []),
+      ...(event.error ? [stringAttribute('lanes.error', event.error.kind)] : []),
+      // Already redacted by the time it reaches any sink — a provider declares
+      // what survives, and the default keeps no values at all. Serialised
+      // rather than flattened into attributes because the shape is nested and
+      // a collector's attribute model is not.
+      stringAttribute('lanes.arguments', JSON.stringify(event.arguments)),
+    ],
+  };
+}
+
+function severityOf(event: AuditEvent): number {
+  if (event.status === 'error') return SEVERITY_ERROR;
+  return event.authorization === 'allowed' ? SEVERITY_INFO : SEVERITY_WARN;
+}
+
+function severityTextOf(event: AuditEvent): string {
+  if (event.status === 'error') return 'ERROR';
+  return event.authorization === 'allowed' ? 'INFO' : 'WARN';
+}
+
+function stringAttribute(key: string, value: string): unknown {
+  return { key, value: { stringValue: value } };
+}

package/src/deployments/adapters/s3.ts

@@ -0,0 +1,195 @@
+import { containedKey } from '#stores/blobs';
+import type { BlobMetadata, BlobStore } from '#stores/blobs';
+
+/**
+ * S3-compatible blob store — the `cloud` target's adapter.
+ *
+ * The workload is the owner layer: `providers/owner/src/memory.ts` writes entry
+ * bodies as blobs, and Cloud Run's disk does not survive an instance recycle.
+ * The filesystem adapter beside this one is not wrong there, it is *silently*
+ * wrong — writes succeed and the bytes are gone with the container.
+ *
+ * `Bun.S3Client` directly, for the reason `postgres.ts` uses `Bun.SQL` and
+ * `sqlite.ts` uses `bun:sqlite`: it is a built-in, so this adapter adds no
+ * dependency to a repository holding live refresh tokens. See ADR-004.
+ *
+ * Named for the protocol rather than the vendor, which is ADR-008's rule
+ * applied to an adapter: Supabase Storage, Cloudflare R2, MinIO, and AWS differ
+ * only in the endpoint. Supabase is what `docs/detailed/deployment-cloudrun.md`
+ * documents, because it is already the Postgres host and a second vendor for
+ * the blobs would be one more thing to hold.
+ *
+ * Containment comes from `containedKey`, not from anything here: `..` in an S3
+ * key is a literal character sequence rather than a directory operation, so the
+ * check is not load-bearing the way `filesystem.ts`'s is. It exists so both
+ * adapters answer identically, which is the only reason the shared contract
+ * suite can assert containment at all.
+ */
+
+export interface S3BlobStoreOptions {
+  readonly bucket: string;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  /**
+   * The S3-compatible service endpoint. Required for anything that is not AWS
+   * — Supabase's is `https://<project-ref>.storage.supabase.co/storage/v1/s3`.
+   */
+  readonly endpoint?: string;
+  readonly region?: string;
+  /**
+   * A key prefix inside the bucket — the bucket-relative equivalent of the
+   * filesystem adapter's `root`, and the same unit of separation. Two profiles
+   * sharing one bucket under different prefixes do not see each other's keys,
+   * and every key this store reports is relative to it.
+   */
+  readonly prefix?: string;
+  /**
+   * Keys requested per `ListObjectsV2` call. Defaults to the protocol's own
+   * ceiling, and exists so a test can force pagination without writing a
+   * thousand objects to prove the continuation-token path is followed.
+   */
+  readonly pageSize?: number;
+}
+
+/**
+ * `ListObjectsV2` returns at most 1000 keys per call whatever `maxKeys` says,
+ * so a store larger than one page is the normal case rather than the edge one.
+ */
+const PAGE_SIZE = 1000;
+
+/**
+ * Whether a read failed because the object is not there.
+ *
+ * `get` and `list` return absence rather than throwing it, so this has to
+ * separate "no such key" from a credential, network, or bucket error — those
+ * must surface. S3 answers `NoSuchKey`; Bun maps some backends' 404 to
+ * `ENOENT`, and a `HeadObject` against a missing key is a bare `NoSuchKey`
+ * with no body, which some implementations report as `AccessDenied` when the
+ * caller lacks `s3:ListBucket`. Only the first two are treated as absence —
+ * swallowing `AccessDenied` would turn a misconfigured policy into an empty
+ * store, which is the failure this whole adapter exists to prevent.
+ */
+function isMissing(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  return code === 'NoSuchKey' || code === 'ENOENT';
+}
+
+/**
+ * A configured prefix as a key prefix: empty, or ending in exactly one slash.
+ *
+ * Exported for its tests. An operator who writes `lanes-link` rather than
+ * `lanes-link/` must not get keys like `lanes-linknote.txt`, and finding that out
+ * should not require a bucket.
+ *
+ * A leading `./` is dropped for the same class of reason. It means "here" to
+ * every path API and means a directory named `.` to a bucket, so a target
+ * declaring `prefix: ./blobs` would silently address `./blobs/…` while every
+ * console, lifecycle rule and IAM condition written against it said `blobs/`.
+ * `layout.ts` no longer produces one; this is for the ones an operator writes.
+ */
+export function s3Prefix(prefix?: string): string {
+  if (prefix === undefined || prefix === '') return '';
+
+  const rooted = prefix.replace(/^(?:\.\/)+/, '');
+  if (rooted === '') return '';
+  return rooted.endsWith('/') ? rooted : `${rooted}/`;
+}
+
+/**
+ * A caller's key as an object key: containment first, then the prefix.
+ *
+ * The order is the point. Prefixing first would let a `../` chew back through
+ * the prefix into another profile's key space, and the containment check would
+ * then see a key that resolves inside the bucket and allow it.
+ */
+export function s3ObjectKey(prefix: string | undefined, key: string): string {
+  return `${s3Prefix(prefix)}${containedKey(key)}`;
+}
+
+export function createS3BlobStore(options: S3BlobStoreOptions): BlobStore {
+  const prefix = s3Prefix(options.prefix);
+  const objectKey = (key: string): string => s3ObjectKey(prefix, key);
+
+  const client = new Bun.S3Client({
+    bucket: options.bucket,
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    ...(options.endpoint !== undefined ? { endpoint: options.endpoint } : {}),
+    ...(options.region !== undefined ? { region: options.region } : {}),
+  });
+
+  /**
+   * Content type is not in a `ListObjectsV2` response, so it costs one
+   * `HeadObject` per key. The filesystem adapter pays the same shape of cost
+   * reading its `.meta` sidecars; here each one is a round trip, so they go
+   * concurrently and a key that vanishes mid-listing is dropped rather than
+   * failing the whole call.
+   */
+  const describe = async (entry: { key: string }): Promise<BlobMetadata | null> => {
+    try {
+      const stat = await client.stat(entry.key);
+      return {
+        key: entry.key.slice(prefix.length),
+        size: stat.size,
+        modifiedAt: stat.lastModified,
+        ...(stat.type ? { contentType: stat.type } : {}),
+      };
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+  };
+
+  return {
+    async put(key, data, blobOptions) {
+      // Uint8Array rather than the caller's view: `write` takes an
+      // ArrayBufferView, and passing one whose byteOffset is non-zero has
+      // uploaded the whole backing buffer on some paths.
+      const bytes = new Uint8Array(data);
+      await client.write(objectKey(key), bytes, {
+        ...(blobOptions?.contentType ? { type: blobOptions.contentType } : {}),
+      });
+    },
+
+    async get(key) {
+      try {
+        return await client.file(objectKey(key)).bytes();
+      } catch (error) {
+        if (isMissing(error)) return null;
+        throw error;
+      }
+    },
+
+    async has(key) {
+      return client.exists(objectKey(key));
+    },
+
+    async delete(key) {
+      // S3 DELETE is idempotent: removing an absent key is a success, which is
+      // the contract the filesystem adapter gets from `rm --force`.
+      await client.delete(objectKey(key));
+    },
+
+    async list(innerPrefix) {
+      const entries: BlobMetadata[] = [];
+      let continuationToken: string | undefined;
+
+      do {
+        const page = await client.list({
+          maxKeys: options.pageSize ?? PAGE_SIZE,
+          prefix: `${prefix}${innerPrefix ?? ''}`,
+          ...(continuationToken !== undefined ? { continuationToken } : {}),
+        });
+
+        const described = await Promise.all((page.contents ?? []).map(describe));
+        for (const entry of described) if (entry) entries.push(entry);
+
+        // `isTruncated` is the authority on whether another page exists; a
+        // present `nextContinuationToken` on a final page would otherwise loop.
+        continuationToken = page.isTruncated ? page.nextContinuationToken : undefined;
+      } while (continuationToken !== undefined);
+
+      return entries.sort((a, b) => a.key.localeCompare(b.key));
+    },
+  };
+}

package/src/deployments/azure/README.md

@@ -0,0 +1,21 @@
+# Azure — not implemented
+
+There is no Azure target. This folder exists to say what one would need, because
+the answer is short and the alternative is someone reading `target.ts` to work it
+out.
+
+Three backends, and two of them already exist:
+
+| Interface | What Azure offers | Adapter |
+|---|---|---|
+| `Database` | Azure Database for PostgreSQL | `adapters/postgres.ts` — **reuse it** |
+| `BlobStore` | Azure Blob Storage | `adapters/s3.ts` if the account has the S3-compatible endpoint enabled, otherwise a new `adapters/azure-blob.ts` |
+| `SecretStore` | Key Vault | new: `adapters/azure-key-vault.ts` |
+
+So the real work is one adapter, plus a `target.ts` here composing the three and
+a deploy driver for Container Apps. Follow `../gcp/` — its `deploy.ts` builds an
+argv array and never a shell string, and its `--dry-run` prints exactly what
+would run.
+
+The one thing not to copy from `../gcp/` is the assumption that `gcloud` is on
+the PATH. That is a property of that deployment, not of deployments generally.

package/src/deployments/bootstrap.ts

@@ -0,0 +1,177 @@
+import { ConfigError, type Config, type DeployConfig, type TargetConfig } from '#profile';
+import { VAULT_KEY_ENV, VAULT_KEY_REF } from '#secrets';
+import { ok, print, style } from '#cli/output.ts';
+import { isInteractive } from '#cli/prompt.ts';
+import { ConfigDocument } from '#cli/config-edit.ts';
+import { driverFor } from './drivers.ts';
+
+/**
+ * Getting a deployable target into the config, by asking rather than refusing.
+ *
+ * Split from `deploy.ts` because it is a different job: that file is the ordered
+ * list of things that have to happen to roll a revision, and this is the one
+ * question it has to settle before any of them — *where*. Keeping them together
+ * put a config editor, a survey and a rollout in one file and pushed it past the
+ * size budget `src/architecture.test.ts` holds.
+ */
+
+export interface TargetBootstrap {
+  /** Override the declared `access` for this run. */
+  readonly access?: string | undefined;
+  readonly serviceAccount?: string | undefined;
+  readonly profile?: string | undefined;
+  /** Take what the config says without asking. Implied when nobody can answer. */
+  readonly nonInteractive?: boolean | undefined;
+}
+
+/**
+ * Whether this run asks its setup questions, or takes the stored answers.
+ *
+ * It asks every time, and that is the point: the values it collects are the ones
+ * that decide where a revision lands, and a deploy where they are invisible
+ * unless you open a YAML file is one you run without reading. Every prompt
+ * defaults to what the config already says, so pressing return through the whole
+ * survey changes nothing and re-generates nothing — the random project and
+ * bucket names are stored values by then, not fresh draws.
+ *
+ * Two things stop it. A run with nobody at the keyboard has to use what is
+ * stored or it dies at the first prompt, which would break every scripted
+ * deploy; and `--non-interactive` says so explicitly, for a terminal that
+ * happens to be attached to a job nobody is watching.
+ *
+ * Neither can rescue a target that is missing the answers. That still refuses,
+ * at the prompt it could not ask.
+ */
+export function willSurvey(
+  declared: TargetConfig | undefined,
+  flags: TargetBootstrap,
+  interactive: boolean,
+): boolean {
+  if (declared?.deploy === undefined) return true;
+  return interactive && flags.nonInteractive !== true;
+}
+
+/**
+ * The target this deploys, asked for whenever the config does not have it.
+ *
+ * Three cases, and the first used to be a refusal. A target that does not exist
+ * at all was `Target "cloud" is not declared` plus a trip to the documentation
+ * to hand-copy four adapter blocks — none of which has more than one workable
+ * answer on a deployment, and one of which (`storage: filesystem`) *appears* to
+ * work and silently discards everything on the next instance recycle. A command
+ * that knows the right answer and refuses to write it is a command that has
+ * chosen to be a worse copy of its own docs.
+ *
+ * Written back to the profile immediately rather than held for the run: the
+ * answers are configuration, and configuration that lives only in a shell
+ * history has to be retyped identically next time or it deploys somewhere else.
+ */
+export async function resolveTarget(input: {
+  config: Config;
+  profilePath: string;
+  workspaceRoot: string;
+  profile: string;
+  target: string;
+  flags: TargetBootstrap;
+}): Promise<TargetConfig> {
+  const { config, flags, target } = input;
+  const declared = config.targets[target];
+  const access = parseAccess(flags.access);
+
+  const overrides = {
+    ...(access ? { access } : {}),
+    ...(flags.serviceAccount !== undefined ? { service_account: flags.serviceAccount } : {}),
+  };
+
+  // Nobody to ask, or told not to: the config is the answer, and flags override
+  // for this run without editing anything.
+  if (!willSurvey(declared, flags, isInteractive())) {
+    return { ...declared!, deploy: { ...declared!.deploy!, ...overrides } };
+  }
+
+  // Only one platform exists, so asking which would be a question with one
+  // answer. When a second lands, this is where it is asked.
+  const driver = await driverFor('cloudrun');
+  const surveyed = await driver.survey({
+    current: { ...(declared?.deploy ?? {}), ...overrides },
+    profile: input.profile,
+    // A profile that authenticates remote clients itself wants the platform
+    // door open; IAM in front of it admits only callers that can mint the
+    // host's own identity token, which is none of them.
+    gated: config.auth.authorization !== undefined,
+    adapters: declared === undefined,
+  });
+
+  const document = await ConfigDocument.open(input.workspaceRoot, input.profile);
+
+  if (declared) {
+    document.setIn(['targets', target, 'deploy'], withoutUndefined(surveyed.target.deploy!));
+  } else {
+    document.setIn(['targets', target], deepWithoutUndefined(surveyed.target));
+  }
+
+  // `auth.authorization` is not part of the target and is written all the same:
+  // the question that decides it is "will a remote client reach this", which
+  // only a deploy is in a position to ask. See `SurveyResult`.
+  if (surveyed.authorization) {
+    document.setIn(['auth', 'authorization'], surveyed.authorization);
+  }
+  await document.save();
+
+  print('');
+  print(
+    ok(
+      declared
+        ? `written to targets.${target}.deploy in ${input.profilePath}`
+        : `written to targets.${target} in ${input.profilePath}`,
+    ),
+  );
+  if (surveyed.authorization) {
+    print(ok('written to auth.authorization — this endpoint will issue its own tokens'));
+  }
+  print(style.dim('  Edit it there, or re-run with --access to change who may reach it.'));
+
+  return declared ? { ...declared, deploy: surveyed.target.deploy } : surveyed.target;
+}
+
+/**
+ * The environment a revision reads out of its own credential store.
+ *
+ * Only the vault key, today. It is here rather than in the driver because
+ * *whether* there is one is a property of the target's adapters, and which
+ * platform mechanism mounts it is not.
+ */
+export function vaultEnv(declared: TargetConfig): Record<string, string> | undefined {
+  const adapter = declared.vault?.adapter;
+  if (adapter !== 'secret' && adapter !== 'blob') return undefined;
+  return { [VAULT_KEY_ENV]: VAULT_KEY_REF };
+}
+
+export function parseAccess(value: string | undefined): DeployConfig['access'] | undefined {
+  if (value === undefined) return undefined;
+  if (value !== 'iam' && value !== 'public') {
+    throw new ConfigError(`--access must be "iam" or "public", not "${value}"`);
+  }
+  return value;
+}
+
+/** `setIn` writes an explicit null for an undefined value, which then fails validation. */
+function withoutUndefined<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  ) as Partial<T>;
+}
+
+/** The same, for a whole target — every block inside it is an object too. */
+export function deepWithoutUndefined<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .map(([key, entry]) => [
+        key,
+        entry !== null && typeof entry === 'object' && !Array.isArray(entry)
+          ? deepWithoutUndefined(entry as object)
+          : entry,
+      ]),
+  ) as Partial<T>;
+}