@crombolo/server 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/server",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "The crombolo HTTP server: routing, configuration, media stores and background jobs.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,17 +28,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/api-delivery": "0.14.1",
-    "@crombolo/api-management": "0.14.1",
-    "@crombolo/assistant": "0.14.1",
-    "@crombolo/auth": "0.14.1",
-    "@crombolo/backoffice-host": "0.14.1",
-    "@crombolo/contracts": "0.14.1",
-    "@crombolo/core": "0.14.1",
-    "@crombolo/data": "0.14.1",
-    "@crombolo/render": "0.14.1",
-    "@crombolo/schema": "0.14.1",
-    "@crombolo/transfer": "0.14.1",
+    "@crombolo/api-delivery": "0.15.0",
+    "@crombolo/api-management": "0.15.0",
+    "@crombolo/assistant": "0.15.0",
+    "@crombolo/auth": "0.15.0",
+    "@crombolo/backoffice-host": "0.15.0",
+    "@crombolo/contracts": "0.15.0",
+    "@crombolo/core": "0.15.0",
+    "@crombolo/data": "0.15.0",
+    "@crombolo/render": "0.15.0",
+    "@crombolo/schema": "0.15.0",
+    "@crombolo/transfer": "0.15.0",
     "@logtape/logtape": "^2.3.8"
   }
 }

package/src/api-client.ts

@@ -0,0 +1,47 @@
+/**
+ * The API client an unattended install seeds (story 034): an API user in the
+ * administrators group, holding the configured client, so a pipeline can sign
+ * in with the client-credentials grant on a site whose backoffice only takes an
+ * identity provider. Created once; a client that exists is never rotated from
+ * config. `docs/operations.md`.
+ */
+import { hashPassword } from '@crombolo/auth'
+import { ADMIN_GROUP_ALIAS } from '@crombolo/core'
+import { BUILT_IN_GROUPS, closeSetup, type Db, UserRepository } from '@crombolo/data'
+import { recordAudit } from './adapters/audit.ts'
+
+/** Seeds the client when no user holds its id; `existed` when one already does. */
+export async function ensureApiClient(
+  db: Db,
+  client: { id: string; secret: string },
+): Promise<'created' | 'existed'> {
+  const users = new UserRepository(db)
+  if (await users.clientCredentialOwner(client.id)) {
+    // A machine can already administer the site, so the browser setup step goes.
+    await closeSetup(db)
+    return 'existed'
+  }
+  const admins = BUILT_IN_GROUPS.find((group) => group.alias === ADMIN_GROUP_ALIAS)
+  const created = await users.create({
+    key: crypto.randomUUID(),
+    name: 'API client',
+    userName: client.id,
+    email: '',
+    kind: 'Api',
+    groupKeys: admins ? [admins.key] : [],
+    languageIsoCode: null,
+  })
+  if (!created) throw new Error(`The API client ${client.id} could not be created.`)
+  await users.addClientCredential(created.id, client.id, await hashPassword(client.secret))
+  await closeSetup(db)
+  await recordAudit(db, {
+    category: 'user',
+    action: 'Create',
+    source: 'cli',
+    entityType: 'User',
+    entityKey: created.key,
+    entityName: client.id,
+    detail: 'API client seeded from CROMBOLO_API_CLIENT_ID',
+  })
+  return 'created'
+}

package/src/atomic-write.ts

@@ -0,0 +1,13 @@
+/**
+ * Writes a file whole or not at all: to a temporary file beside it, then a
+ * rename, so a crash or a second process never sees half of it.
+ */
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export function writeFileAtomic(path: string, data: string | Uint8Array): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  writeFileSync(temporary, data)
+  renameSync(temporary, path)
+}

package/src/bundle-install.ts

@@ -524,15 +524,32 @@ export async function installBundleContent(
     return refuse([
       'this file was written without its media files (--no-media); pass --allow-missing-media to import the media items without them',
     ])
+  // Referenced media arrives in the store one file at a time, before the file
+  // that names it (story 107): every one has to be there already.
+  let referencedPresent = false
+  if (manifest.media === 'referenced') {
+    const store = await mediaStoreFor(config)
+    const absent: string[] = []
+    for (const blob of manifest.blobs) if (!(await store.get(blob.key))) absent.push(blob.key)
+    if (absent.length > 0 && !input.allowMissingBlobs)
+      return refuse([
+        `${absent.length} media file(s) this file refers to are not in the media store yet`,
+        ...absent,
+      ])
+    referencedPresent = true
+  }
   if (replace === 'replace-all' && !carriesAdministrator(set.people))
     return refuse([
       'this file carries no back-office administrator, so replacing everything would leave nobody able to sign in; export it with --with-users, or use --replace',
     ])
 
   // A replace takes the file's side of every difference, and replaces files.
-  const effective: ContentImportInput = replace
+  const replaced: ContentImportInput = replace
     ? { ...input, resolveAll: 'take-bundle', replaceFiles: true, publish: input.publish ?? true }
     : input
+  const effective: ContentImportInput = referencedPresent
+    ? { ...replaced, allowMissingBlobs: true }
+    : replaced
 
   // The coarse layer, under the fine-grained revert: in-place conversion is not
   // reversible by itself, so the same rule as `upgrade` applies here.

package/src/config.ts

@@ -1,7 +1,11 @@
 import { hostname, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import type { DeliveryApiOptions } from '@crombolo/api-delivery'
-import { DEFAULT_BACKOFFICE_PATH } from '@crombolo/core'
+import {
+  DEFAULT_BACKOFFICE_PATH,
+  DEFAULT_PASSWORD_CONFIGURATION,
+  isValidPassword,
+} from '@crombolo/core'
 import { DEFAULT_RENDER_TIMEOUT_MS, type RedirectRule, type SnapshotLimits } from '@crombolo/render'
 import type { AssistantConfig } from './assistant.ts'
 import type { ServerBundle } from './bundles.ts'
@@ -30,6 +34,65 @@ export type UserLinkSender = (message: {
   message: string | null
 }) => Promise<void>
 
+export interface RemoteSettings {
+  enabled: boolean
+  /** The environment this server is, as the remote protocol names it. */
+  environment: string
+  /** A push here replaces something people rely on: it needs its own permission. */
+  protected: boolean
+  /** A push to a protected environment waits for another person's approval. */
+  approvals: boolean
+  /**
+   * The largest push file or media file a client may upload. Every other route
+   * keeps `maxRequestBodyBytes`, checked per request, since Bun's own limit is
+   * the server's.
+   */
+  maxUploadBytes: number
+}
+
+/** The prefix every API client id carries, as the Management API requires. */
+export const API_CLIENT_ID_PREFIX = 'crombolo-back-office-'
+
+/** Refuses a seeded API client that the Management API would refuse, naming the variable. */
+function checkApiClient(client: CromboloConfig['apiClient']): void {
+  if (!client) return
+  if (!client.id || !client.secret)
+    throw new Error(
+      'CROMBOLO_API_CLIENT_ID and CROMBOLO_API_CLIENT_SECRET go together: set both, or neither.',
+    )
+  if (
+    !client.id.startsWith(API_CLIENT_ID_PREFIX) ||
+    client.id.length <= API_CLIENT_ID_PREFIX.length
+  )
+    throw new Error(`CROMBOLO_API_CLIENT_ID must start with "${API_CLIENT_ID_PREFIX}".`)
+  if (!isValidPassword(client.secret))
+    throw new Error(
+      `CROMBOLO_API_CLIENT_SECRET must be at least ${DEFAULT_PASSWORD_CONFIGURATION.minimumPasswordLength} characters.`,
+    )
+}
+
+/**
+ * Whether this site runs on the developer's own machine: development, and an
+ * application URL that is unset or names localhost. What `localAdmin` needs.
+ */
+export function runsOnLocalhost(config: CromboloConfig): boolean {
+  if (!config.development) return false
+  if (!config.applicationUrl) return true
+  try {
+    const host = new URL(config.applicationUrl).hostname
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1'
+  } catch {
+    return false
+  }
+}
+
+/** The body limit to listen with: raised for remote uploads when the remote is on. */
+export function listeningBodyLimit(config: CromboloConfig): number {
+  return config.remote.enabled
+    ? Math.max(config.maxRequestBodyBytes, config.remote.maxUploadBytes)
+    : config.maxRequestBodyBytes
+}
+
 export interface CromboloConfig {
   port: number
   /** The largest request body the server will read, media uploads included. */
@@ -74,6 +137,20 @@ export interface CromboloConfig {
   adminPassword: string | undefined
   /** Guards "Set up your new site". Chosen by the owner; never printed, logged or shown. */
   setupCode: string | undefined
+  /**
+   * The API client an unattended install seeds (story 034), so a pipeline can
+   * administer a site whose backoffice only takes an identity provider. Seeded
+   * once and never rotated from here; the secret is never printed or logged.
+   * With it set, no password administrator is seeded unless `adminPassword` is
+   * — or `localAdmin` is, on a site running on localhost.
+   */
+  apiClient: { id: string; secret: string } | undefined
+  /**
+   * Seed the password administrator even with `apiClient` set, so local
+   * development keeps printing a sign-in. Honoured only on localhost
+   * (`runsOnLocalhost`); ignored, with a warning, anywhere else.
+   */
+  localAdmin: boolean
   /** Seals secrets kept in the database, such as a webhook's headers; never stored. */
   secretKey: string | undefined
   /**
@@ -153,7 +230,7 @@ export interface CromboloConfig {
    * CROMBOLO_SCHEMA_WRITABLE says otherwise outright.
    */
   schemaWritable: boolean
-  /** Sync `schema/` at boot; a pipeline that runs `crombolo schema sync` turns this off. */
+  /** Sync `schema/` at boot; a pipeline that runs `crombolo types sync` turns this off. */
   syncSchemaAtBoot: boolean
   /** Which database engine; from CROMBOLO_DB. */
   dialect: 'sqlite' | 'postgres'
@@ -241,6 +318,15 @@ export interface CromboloConfig {
   memberIdentityProviders: readonly IdentityProvider[]
   /** Identity providers backoffice users may sign in with. `allowLocalLogin: false` makes them the only way in. */
   backofficeIdentityProviders: readonly IdentityProvider[]
+  /**
+   * Answering the remote protocol (story 107): a developer's `crombolo` pulls a
+   * copy of this site and pushes work back. Off unless `enabled`. This server
+   * offers one environment, itself, named `environment`; `protected` makes a
+   * push need the protected-push permission, and `approvals` makes it wait for
+   * someone else with that permission to approve it, which needs
+   * `CROMBOLO_SECRET_KEY`. docs/remote-protocol.md.
+   */
+  remote: RemoteSettings
   /**
    * Redirects the site declares itself, built with `redirect()`. They are synced
    * into the database at boot, so the backoffice lists them beside the tracked
@@ -427,6 +513,14 @@ export function loadConfig(
     sqliteFile: Bun.env.CROMBOLO_SQLITE_FILE ?? DEFAULTS.sqliteFile,
     adminLogin: Bun.env.CROMBOLO_ADMIN_LOGIN ?? DEFAULTS.adminLogin,
     adminPassword: Bun.env.CROMBOLO_ADMIN_PASSWORD,
+    apiClient:
+      Bun.env.CROMBOLO_API_CLIENT_ID || Bun.env.CROMBOLO_API_CLIENT_SECRET
+        ? {
+            id: Bun.env.CROMBOLO_API_CLIENT_ID ?? '',
+            secret: Bun.env.CROMBOLO_API_CLIENT_SECRET ?? '',
+          }
+        : undefined,
+    localAdmin: Bun.env.CROMBOLO_LOCAL_ADMIN === 'true',
     setupCode: Bun.env.CROMBOLO_SETUP_CODE,
     secretKey: Bun.env.CROMBOLO_SECRET_KEY,
     secureCookies: Bun.env.CROMBOLO_INSECURE_COOKIES !== 'true',
@@ -514,6 +608,13 @@ export function loadConfig(
     // No environment variable: a provider is a preset, which is code.
     memberIdentityProviders: [],
     backofficeIdentityProviders: [],
+    remote: {
+      enabled: Bun.env.CROMBOLO_REMOTE_ENABLED === 'true',
+      environment: Bun.env.CROMBOLO_REMOTE_ENVIRONMENT || 'production',
+      protected: Bun.env.CROMBOLO_REMOTE_PROTECTED !== 'false',
+      approvals: Bun.env.CROMBOLO_REMOTE_APPROVALS === 'true',
+      maxUploadBytes: Number(Bun.env.CROMBOLO_REMOTE_MAX_UPLOAD_GB ?? 50) * 1024 ** 3,
+    },
     redirects: [],
     trackRedirects: Bun.env.CROMBOLO_TRACK_REDIRECTS !== 'false',
     applyBundleContentOnInstall: Bun.env.CROMBOLO_APPLY_BUNDLE_CONTENT !== 'false',
@@ -545,6 +646,12 @@ export function loadConfig(
   checkIdentityProviders(merged.backofficeIdentityProviders, 'backoffice')
   // Field by field, so a site setting its title suffix keeps the environment's switches.
   merged.seo = { ...fromEnv.seo, ...stripUndefined(overrides.seo ?? {}) }
+  merged.remote = { ...fromEnv.remote, ...stripUndefined(overrides.remote ?? {}) }
+  checkApiClient(merged.apiClient)
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(merged.remote.environment))
+    throw new Error(
+      `remote.environment "${merged.remote.environment}" must be lower case letters, digits and dashes.`,
+    )
   merged.deliveryApi = {
     ...fromEnv.deliveryApi,
     ...stripUndefined(overrides.deliveryApi ?? {}),
@@ -632,4 +739,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.14.1'
+export const VERSION = '0.15.0'

package/src/database.ts

@@ -21,8 +21,10 @@ import {
   seedContent,
   seedIdentity,
 } from '@crombolo/data'
+import { ensureApiClient } from './api-client.ts'
 import { type BundleChain, migrateBundles, pendingBundleSteps } from './bundle-tables.ts'
-import type { CromboloConfig } from './config.ts'
+import { type CromboloConfig, runsOnLocalhost } from './config.ts'
+import { logger } from './logging.ts'
 
 /** Production never auto-upgrades: an existing database with steps pending refuses to boot. */
 export class UpgradePendingError extends Error {
@@ -127,17 +129,28 @@ export async function installDatabase(
   await migrateBundles(db, chains, { by: config.nodeId })
 
   // In production a password is never made up: the pipeline supplies one, or
-  // the owner sets the site up in the browser (docs/operations.md).
-  const settingUp = !config.development && !config.adminPassword
-  const password = config.adminPassword ?? crypto.randomUUID().replaceAll('-', '').slice(0, 20)
+  // the owner sets the site up in the browser (docs/operations.md). With an API
+  // client to seed (story 034) a machine administers the site instead, and no
+  // password administrator exists unless asked for — `adminPassword`, or
+  // `localAdmin` on the developer's own machine.
+  const localAdmin = config.localAdmin && runsOnLocalhost(config)
+  if (config.localAdmin && !localAdmin)
+    logger('install').warning(
+      'CROMBOLO_LOCAL_ADMIN is ignored: this site does not run on localhost',
+    )
+  const machineOnly = config.apiClient !== undefined && !config.adminPassword && !localAdmin
+  const settingUp = !machineOnly && !config.development && !config.adminPassword
+  const password = config.adminPassword || crypto.randomUUID().replaceAll('-', '').slice(0, 20)
   const seeded = await seedIdentity(db, {
-    admin: settingUp
-      ? undefined
-      : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
+    admin:
+      settingUp || machineOnly
+        ? undefined
+        : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
     hashPassword,
     passwordConfig: passwordConfigJson(),
   })
   if (seeded && settingUp) await markSetupPending(db)
+  if (config.apiClient) await ensureApiClient(db, config.apiClient)
 
   await seedContent(db)
   // A database from an older version gains the built-ins it lacks.
@@ -146,5 +159,5 @@ export async function installDatabase(
   await ensureSystemMemberTypes(db)
   await ensureSystemContentTypes(db)
 
-  return seeded && !settingUp && !config.adminPassword ? password : undefined
+  return seeded && !settingUp && !machineOnly && !config.adminPassword ? password : undefined
 }

package/src/domains.ts

@@ -25,6 +25,7 @@ import {
   type NodeRow,
   resolveNodeRef,
 } from '@crombolo/data'
+import { writeFileAtomic } from './atomic-write.ts'
 
 export const DOMAINS_FILE = 'domains.toml'
 
@@ -152,8 +153,8 @@ export async function writeDomains(
   const file = domainsFilePath(siteDir)
   const backup = join(siteDir, DOMAINS_BACKUP_FILE)
   const kept = existsSync(file) ? readFileSync(file, 'utf8') : undefined
-  if (kept !== undefined) await Bun.write(backup, kept)
-  await Bun.write(file, writeDomainsFile(declarations))
+  if (kept !== undefined) writeFileAtomic(backup, kept)
+  writeFileAtomic(file, writeDomainsFile(declarations))
   return { file, backup: kept === undefined ? undefined : backup }
 }
 
@@ -167,10 +168,10 @@ export async function undoDomainsFile(
     return { ok: false, file, message: `there is no ${DOMAINS_BACKUP_FILE} to go back to` }
   const previous = readFileSync(backup, 'utf8')
   const current = existsSync(file) ? readFileSync(file, 'utf8') : undefined
-  await Bun.write(file, previous)
+  writeFileAtomic(file, previous)
   // So that undo is itself undoable, which is what somebody who has just undone
   // the wrong thing needs.
-  await Bun.write(backup, current ?? '')
+  writeFileAtomic(backup, current ?? '')
   return { ok: true, file }
 }
 

package/src/index.ts

@@ -12,6 +12,8 @@ export * from './adapters/public-access.ts'
 export * from './adapters/redirects.ts'
 export * from './adapters/references.ts'
 export * from './adapters/template-files.ts'
+export * from './api-client.ts'
+export * from './atomic-write.ts'
 export * from './backup.ts'
 export * from './boot-failure.ts'
 export * from './bundle-install.ts'
@@ -63,6 +65,9 @@ export * from './no-nodes.ts'
 export * from './oembed.ts'
 export * from './ports.ts'
 export * from './redirects.ts'
+export * from './remote.ts'
+export * from './remote-credentials.ts'
+export * from './remote-media.ts'
 export * from './schema.ts'
 export * from './schema-store.ts'
 export * from './secrets.ts'

package/src/media-store-azure.ts

@@ -168,7 +168,7 @@ export function azureMediaStore(options: AzureMediaStoreOptions): MediaStore {
     async put(key, body, putOptions) {
       if (!isSafeMediaKey(key)) throw new Error(`"${key}" is not a usable media key.`)
       // Copied into a plain ArrayBuffer so `fetch` and the signature agree on its length.
-      const bytes = new Uint8Array(body instanceof File ? await body.arrayBuffer() : body)
+      const bytes = new Uint8Array(body instanceof Blob ? await body.arrayBuffer() : body)
       const response = await send('PUT', blobUrl(key), {
         body: bytes,
         headers: {

package/src/media-store.ts

@@ -13,6 +13,7 @@
  *   `ab12cd34/photo.jpg`        a placed file, served at `/media/ab12cd34/photo.jpg`
  *   `.temp/<uuid>/photo.jpg`    an upload not yet placed, with `meta.json` beside it
  *   `.cache/ab/<hash>.webp`     a processed image variant
+ *   `.remote/<job>/site.tgz`    a remote pull's or push's file (story 107), never public
  *
  * A site picks a store in `crombolo.config.ts` — `fileSystemMediaStore`,
  * `s3MediaStore` or `azureMediaStore` — or leaves it to the environment, which
@@ -41,7 +42,7 @@ export interface MediaStore {
   /** Named in the boot banner and in logs: `media/`, `s3://bucket`, … */
   readonly description: string
   get(key: string): Promise<StoredFile | undefined>
-  put(key: string, body: Uint8Array | File, options?: { contentType?: string }): Promise<void>
+  put(key: string, body: Uint8Array | Blob, options?: { contentType?: string }): Promise<void>
   delete(key: string): Promise<void>
   /** Every key under a prefix, which is how temporary uploads are swept. */
   list(prefix: string): Promise<string[]>
@@ -111,7 +112,8 @@ export function isSafeMediaKey(key: string): boolean {
       part !== '' &&
       part !== '.' &&
       part !== '..' &&
-      (!part.startsWith('.') || (index === 0 && (part === '.temp' || part === '.cache'))),
+      (!part.startsWith('.') ||
+        (index === 0 && (part === '.temp' || part === '.cache' || part === '.remote'))),
   )
 }
 

package/src/member-auth.ts

@@ -359,7 +359,11 @@ export function createMemberAuth(
     // Checked before the password, so the answer never depends on whether the
     // password was right; the same throwaway verify as above keeps the time taken
     // from saying what the response does not.
-    if (member.isLockedOut || !member.isApproved) {
+    // A member with no password signs in only through a provider (story 035).
+    // Refused like a wrong password, in the same time, and not counted: a
+    // stranger's guesses must not lock out the provider sign-in, nor say that
+    // the account has no password.
+    if (member.isLockedOut || !member.isApproved || !member.passwordHash) {
       await verifyPassword(input.password ?? '', await hashPassword(crypto.randomUUID()))
       return failed()
     }

package/src/remote-credentials.ts

@@ -0,0 +1,108 @@
+/**
+ * A developer's sign-ins to remotes (story 108): kept in the operating system's
+ * keychain (macOS Keychain, Windows Credential Manager, libsecret) through
+ * `Bun.secrets`, keyed by the remote's origin, never in the site's folder.
+ * Shared by the CLI's commands and a lazily-fetching local media store.
+ */
+
+export const KEYCHAIN_SERVICE = 'crombolo-remote'
+
+export interface Keychain {
+  get(name: string): Promise<string | null>
+  set(name: string, value: string): Promise<void>
+  delete(name: string): Promise<void>
+}
+
+/** The operating system's keychain. */
+export function osKeychain(): Keychain {
+  return {
+    get: (name) => Bun.secrets.get({ service: KEYCHAIN_SERVICE, name }),
+    set: (name, value) => Bun.secrets.set({ service: KEYCHAIN_SERVICE, name, value }),
+    delete: async (name) => {
+      await Bun.secrets.delete({ service: KEYCHAIN_SERVICE, name })
+    },
+  }
+}
+
+/** A keychain in memory, for tests and machines without one. */
+export function memoryKeychain(): Keychain {
+  const values = new Map<string, string>()
+  return {
+    get: async (name) => values.get(name) ?? null,
+    set: async (name, value) => {
+      values.set(name, value)
+    },
+    delete: async (name) => {
+      values.delete(name)
+    },
+  }
+}
+
+export interface RemoteSignIn {
+  accessToken: string
+  refreshToken: string
+  /** Milliseconds since the epoch. */
+  expiresAt: number
+  tokenUrl: string
+  clientId: string
+  /** Who approved it, for `whoami`. */
+  user?: string
+}
+
+const keyOf = (origin: string) => new URL(origin).origin
+
+export async function readSignIn(
+  keychain: Keychain,
+  origin: string,
+): Promise<RemoteSignIn | undefined> {
+  const stored = await keychain.get(keyOf(origin))
+  if (!stored) return undefined
+  try {
+    return JSON.parse(stored) as RemoteSignIn
+  } catch {
+    return undefined
+  }
+}
+
+export const saveSignIn = (keychain: Keychain, origin: string, signIn: RemoteSignIn) =>
+  keychain.set(keyOf(origin), JSON.stringify(signIn))
+
+export const forgetSignIn = (keychain: Keychain, origin: string) => keychain.delete(keyOf(origin))
+
+/**
+ * A usable access token: the stored one, or a refreshed one when it is within a
+ * minute of expiring. Undefined when there is no sign-in, or the remote refused
+ * the refresh — the person signs in again.
+ */
+export async function freshAccessToken(
+  keychain: Keychain,
+  origin: string,
+  http: typeof fetch = fetch,
+  force = false,
+): Promise<string | undefined> {
+  const signIn = await readSignIn(keychain, origin)
+  if (!signIn) return undefined
+  if (!force && signIn.expiresAt - Date.now() > 60_000) return signIn.accessToken
+  const response = await http(signIn.tokenUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: signIn.refreshToken,
+      client_id: signIn.clientId,
+    }).toString(),
+  })
+  if (!response.ok) return undefined
+  const tokens = (await response.json()) as {
+    access_token: string
+    refresh_token: string
+    expires_in: number
+  }
+  await saveSignIn(keychain, origin, {
+    ...signIn,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt: Date.now() + tokens.expires_in * 1000,
+  })
+  return tokens.access_token
+}

package/src/remote-media.ts

@@ -0,0 +1,91 @@
+/**
+ * Media fetched from a remote on first request (story 108, `pull
+ * --media-info-only --lazy-media`): a local site pulled without its media
+ * files reads each one through from the remote it came from the first time it
+ * is asked for, under the developer's own sign-in, and keeps it.
+ *
+ * Only the store the site serves from is wrapped. An export reads the plain
+ * store, so pushing a lazily-pulled site never downloads what it never used.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { writeFileAtomic } from './atomic-write.ts'
+import { logger } from './logging.ts'
+import type { MediaStore, StoredFile } from './media-store.ts'
+import { freshAccessToken, type Keychain, osKeychain } from './remote-credentials.ts'
+
+export const REMOTE_MEDIA_FILE = join('.crombolo', 'remote-media.json')
+
+export interface RemoteMediaSource {
+  /** The remote's API base, which is also what its sign-in is kept under. */
+  api: string
+  environment: string
+}
+
+export function readRemoteMedia(siteDir: string): RemoteMediaSource | undefined {
+  const file = join(siteDir, REMOTE_MEDIA_FILE)
+  if (!existsSync(file)) return undefined
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<RemoteMediaSource>
+    return typeof parsed.api === 'string' && typeof parsed.environment === 'string'
+      ? { api: parsed.api, environment: parsed.environment }
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function writeRemoteMedia(siteDir: string, source: RemoteMediaSource): void {
+  const file = join(siteDir, REMOTE_MEDIA_FILE)
+  writeFileAtomic(file, `${JSON.stringify(source, null, 2)}\n`)
+}
+
+/** The site's store, reading through to its remote when the site was pulled lazily. */
+export function withRemoteMedia(
+  store: MediaStore,
+  siteDir: string,
+  options: { keychain?: Keychain; http?: typeof fetch } = {},
+): MediaStore {
+  const source = readRemoteMedia(siteDir)
+  if (!source) return store
+  const keychain = options.keychain ?? osKeychain()
+  const http = options.http ?? fetch
+  const log = logger('media')
+  let warned = false
+
+  const fetchThrough = async (key: string): Promise<StoredFile | undefined> => {
+    const token = await freshAccessToken(keychain, source.api, http)
+    if (!token) {
+      if (!warned)
+        log.warning(
+          'A media file is not here yet, and fetching it needs `crombolo login` to {api}',
+          {
+            api: source.api,
+          },
+        )
+      warned = true
+      return undefined
+    }
+    const path = key.split('/').map(encodeURIComponent).join('/')
+    const response = await http(`${source.api}/environments/${source.environment}/media/${path}`, {
+      headers: { authorization: `Bearer ${token}` },
+    }).catch(() => undefined)
+    if (!response?.ok) return undefined
+    await store.put(key, await response.blob())
+    return store.get(key)
+  }
+
+  return {
+    ...store,
+    description: `${store.description} (fetching from ${new URL(source.api).origin})`,
+    async get(key) {
+      const local = await store.get(key)
+      if (local || key.startsWith('.')) return local
+      return fetchThrough(key)
+    },
+    put: (key, body, putOptions) => store.put(key, body, putOptions),
+    delete: (key) => store.delete(key),
+    list: (prefix) => store.list(prefix),
+    ...(store.publicUrl ? { publicUrl: (key: string) => store.publicUrl?.(key) } : {}),
+  }
+}