@devfn/config 0.1.0 → 0.1.1

package/dist/credentials.d.ts

@@ -0,0 +1,5 @@
+/** Credential names are aliases delimited by separators or case boundaries,
+ * or documented compact qualifier/alias pairs. */
+export declare function isCredentialKey(name: string): boolean;
+/** Reject keys that would alias on case-insensitive process environments. */
+export declare function assertEnvironmentKeyCasing(...groups: ReadonlyArray<Iterable<string>>): void;

package/dist/credentials.js

@@ -0,0 +1,71 @@
+/** Shared grammar for environment keys, argv flags and URL parameters. */
+const CREDENTIAL_ALIASES = new Set([
+    "accesskey", "accesskeyid", "accesstoken", "apikey", "apikeys", "auth", "authkey", "authorization", "authtoken",
+    "bearer", "clientsecret", "cookie", "cred", "credential", "credentials", "creds", "key", "passwd", "password",
+    "pass", "passcode", "passkey", "passphrase", "privatekey", "pwd", "refreshtoken", "secret", "secretkey", "sessionid", "sessiontoken",
+    "sig", "signature", "token", "pat", "phpsessid", "xamzcredential", "xamzsignature", "xgoogcredential", "xgoogsignature",
+]);
+// Compact names have no word boundary. Support known qualifier + alias pairs;
+// otherwise words such as monkey and compass would be false positives.
+const COMPACT_QUALIFIERS = new Set([
+    "api", "app", "auth", "aws", "client", "db", "database", "google", "oauth", "pg", "server", "service", "session", "user", "xamz", "xgoog",
+]);
+// These suffixes identify credentials even with an application-specific
+// qualifier that DevFn cannot enumerate (for example GITHUBTOKEN).
+// Short ambiguous suffixes such as key, pass and sig still require a known
+// qualifier or a word boundary, so MONKEY and COMPASS remain ordinary names.
+const UNAMBIGUOUS_SUFFIXES = [
+    "password", "passwd", "passphrase", "passcode", "passkey", "secret", "token", "credential", "credentials",
+    "apikey", "apikeys", "accesskey",
+    "secretkey", "accesskeyid",
+    "privatekey", "sessionid", "sessiontoken", "authorization",
+];
+function words(name) {
+    // Numbered copies of a credential field retain the field's meaning.
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/).map((word) => {
+        let end = word.length;
+        while (end > 0 && (word.codePointAt(end - 1) ?? 0) >= 48 && (word.codePointAt(end - 1) ?? 0) <= 57)
+            end -= 1;
+        return word.slice(0, end).toLowerCase();
+    }).filter(Boolean);
+}
+function compactCredential(name, qualifiers = 0) {
+    if (qualifiers > 0 && CREDENTIAL_ALIASES.has(name))
+        return true;
+    if (qualifiers === 3)
+        return false;
+    for (const qualifier of COMPACT_QUALIFIERS) {
+        if (name.startsWith(qualifier) && name.length > qualifier.length && compactCredential(name.slice(qualifier.length), qualifiers + 1))
+            return true;
+        if (name.endsWith(qualifier) && name.length > qualifier.length && compactCredential(name.slice(0, -qualifier.length), qualifiers + 1))
+            return true;
+    }
+    return false;
+}
+/** Credential names are aliases delimited by separators or case boundaries,
+ * or documented compact qualifier/alias pairs. */
+export function isCredentialKey(name) {
+    const parts = words(name);
+    for (let start = 0; start < parts.length; start += 1) {
+        for (let end = start + 1; end <= Math.min(parts.length, start + 3); end += 1) {
+            if (CREDENTIAL_ALIASES.has(parts.slice(start, end).join("")))
+                return true;
+        }
+    }
+    const compact = parts.join("");
+    return compactCredential(compact) || UNAMBIGUOUS_SUFFIXES.some((suffix) => compact.length > suffix.length && compact.endsWith(suffix));
+}
+/** Reject keys that would alias on case-insensitive process environments. */
+export function assertEnvironmentKeyCasing(...groups) {
+    const seen = new Map();
+    for (const group of groups)
+        for (const key of group) {
+            const folded = key.toUpperCase();
+            const previous = seen.get(folded);
+            if (previous && previous !== key)
+                throw new Error(`Environment key ${key} collides with ${previous} after case folding.`);
+            seen.set(folded, key);
+        }
+}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { DevFnConfigError, type ConfigErrorCode } from "./errors.js";
+export { isCredentialKey, assertEnvironmentKeyCasing } from "./credentials.js";
 export { discoverProject, renderDevFnConfig } from "./discovery.js";
 export { DEVFN_CONFIG_CANDIDATES, findDevFnRoot, loadDevFnConfig, loadDevFnPolicy, loadTrustedDevFnConfig, resolveDevFnManifestPath } from "./load.js";
 export { resolveContainedPath } from "./paths.js";
-export { matchesProcessIdentity, processBirthSignature, processExists } from "./process-identity.js";
-export { validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
+export { classifyLegacyDarwinIdentity, classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature, type ProcessGroupStatus, type ProcessIdentityStatus } from "./process-identity.js";
+export { resourceEnvironmentKeys, resourceToken, validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
 export { configDigest, defaultStateDir, isProjectTrusted, readTrustedManifest, trustProject } from "./trust.js";
 export type * from "./types.js";
 export declare function defineDevFnConfig<T extends import("./types.js").DevFnConfig>(config: T): T;

package/dist/index.js

@@ -1,9 +1,10 @@
 export { DevFnConfigError } from "./errors.js";
+export { isCredentialKey, assertEnvironmentKeyCasing } from "./credentials.js";
 export { discoverProject, renderDevFnConfig } from "./discovery.js";
 export { DEVFN_CONFIG_CANDIDATES, findDevFnRoot, loadDevFnConfig, loadDevFnPolicy, loadTrustedDevFnConfig, resolveDevFnManifestPath } from "./load.js";
 export { resolveContainedPath } from "./paths.js";
-export { matchesProcessIdentity, processBirthSignature, processExists } from "./process-identity.js";
-export { validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
+export { classifyLegacyDarwinIdentity, classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature } from "./process-identity.js";
+export { resourceEnvironmentKeys, resourceToken, validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
 export { configDigest, defaultStateDir, isProjectTrusted, readTrustedManifest, trustProject } from "./trust.js";
 export function defineDevFnConfig(config) { return config; }
 export function defineDevFnPolicy(policy) { return policy; }

package/dist/process-identity.d.ts

@@ -1,3 +1,48 @@
 export declare function processBirthSignature(pid: number): Promise<string | undefined>;
+/**
+ * The birth signature of a process just started, read up to ten times 20 ms
+ * apart: a single ps or /proc read may miss it transiently. Undefined only
+ * when every read failed.
+ */
+export declare function startedProcessBirthSignature(pid: number): Promise<string | undefined>;
+/** Whether the PID is a live process; a zombie is not one. */
 export declare function processExists(pid: number): boolean;
-export declare function matchesProcessIdentity(pid: number, signature?: string): Promise<boolean>;
+export type ProcessIdentityStatus = "running" | "exited" | "identity-mismatch" | "unverified";
+/**
+ * Only an absent PID or a readable birth signature that differs proves a
+ * recorded process is gone. A live PID whose recorded or current signature
+ * is unknown may still be that process.
+ */
+export declare function classifyProcessIdentity(exists: boolean, recorded?: string, current?: string): ProcessIdentityStatus;
+/**
+ * Judge a live PID against a legacy darwin: signature. Earlier releases
+ * rendered its start time in the recording caller's time zone and locale,
+ * so neither an equal nor a different reading proves anything here. The
+ * record's own UTC time decides instead: DevFn writes it only after reading
+ * the signature of a live owner, so a process that started after it is a
+ * different process reusing the PID, and one that started no later was
+ * alive under that PID when the record was written and so is its owner.
+ * Without a record time, or within the clock tolerance, nothing is proven.
+ */
+export declare function classifyLegacyDarwinIdentity(pinnedStartTime: string | undefined, recordedAt: string | undefined): ProcessIdentityStatus;
+/**
+ * recordedAt is the UTC time the identity was recorded, after it was read
+ * from the live process; it decides only legacy darwin: signatures.
+ */
+export declare function processIdentityStatus(pid: number, signature?: string, recordedAt?: string): Promise<ProcessIdentityStatus>;
+export type ProcessGroupStatus = "running" | "unverified" | "exited" | "identity-mismatch";
+/**
+ * Whether anything a recorded process group leader ran may still run. On
+ * POSIX the leader's PID is its group ID, and a PID is not reused while a
+ * group with that ID exists, so:
+ * - a reused PID ("identity-mismatch") proves the original group gone;
+ * - an exited leader whose group still has members is "unverified": those
+ *   members are what it started, unless the group was emptied and a later
+ *   process reusing the PID started another, which DevFn cannot tell apart;
+ * - only "exited" (leader and group gone, or only zombies left) and
+ *   "identity-mismatch" are death evidence. Windows has no process groups;
+ *   only the leader is judged.
+ */
+export declare function processGroupStatus(pid: number, signature?: string, recordedAt?: string): Promise<ProcessGroupStatus>;
+/** Whether the PID is verifiably the recorded process, as required before signalling it. */
+export declare function matchesProcessIdentity(pid: number, signature?: string, recordedAt?: string): Promise<boolean>;

package/dist/process-identity.js

@@ -1,21 +1,39 @@
 import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+async function darwinStartTime(pid, env) {
+    const { stdout } = await execFileAsync("ps", ["-o", "lstart=", "-p", String(pid)], { env });
+    return stdout.trim() || undefined;
+}
+// ps renders the start time in the caller's time zone and locale; pin both
+// so every DevFn invocation reads the same process the same way.
+const PINNED_PS_ENVIRONMENT = { TZ: "UTC0", LC_ALL: "C" };
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** The start second, in epoch milliseconds, of a ps lstart reading taken in the pinned environment. */
+function parsePinnedStartTime(text) {
+    const match = /^[A-Z][a-z]{2} ([A-Z][a-z]{2}) +(\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/.exec(text);
+    const month = match ? MONTHS.indexOf(match[1]) : -1;
+    if (!match || month < 0)
+        return undefined;
+    const [, , day, hours, minutes, seconds, year] = match.map(Number);
+    return Date.UTC(year, month, day, hours, minutes, seconds);
+}
 export async function processBirthSignature(pid) {
     try {
         if (process.platform === "linux") {
-            const stat = await import("node:fs/promises").then((fs) => fs.readFile(`/proc/${pid}/stat`, "utf8"));
-            const afterCommand = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
-            const startTime = afterCommand[19];
+            const startTime = linuxStatFields(await readFile(`/proc/${pid}/stat`, "utf8"))[19];
             return startTime ? `linux:${startTime}` : undefined;
         }
         if (process.platform === "darwin") {
-            const { stdout } = await execFileAsync("ps", ["-o", "lstart=", "-p", String(pid)]);
-            return `darwin:${stdout.trim()}`;
+            const startTime = await darwinStartTime(pid, { ...process.env, ...PINNED_PS_ENVIRONMENT });
+            return startTime ? `darwin-utc:${startTime}` : undefined;
         }
         if (process.platform === "win32") {
             const { stdout } = await execFileAsync("powershell", ["-NoProfile", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().ToString('O')`]);
-            return `win32:${stdout.trim()}`;
+            const startTime = stdout.trim();
+            return startTime ? `win32:${startTime}` : undefined;
         }
     }
     catch {
@@ -23,19 +41,210 @@ export async function processBirthSignature(pid) {
     }
     return undefined;
 }
+/**
+ * The birth signature of a process just started, read up to ten times 20 ms
+ * apart: a single ps or /proc read may miss it transiently. Undefined only
+ * when every read failed.
+ */
+export async function startedProcessBirthSignature(pid) {
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        if (attempt > 0)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        const signature = await processBirthSignature(pid);
+        if (signature)
+            return signature;
+    }
+    return undefined;
+}
+/** The /proc/<pid>/stat fields after the command name: state, ppid, pgrp, ... */
+function linuxStatFields(stat) {
+    return stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+}
+// A zombie has exited but keeps its PID and group ID until its parent reaps
+// it, which a container PID 1 that does not reap never does. It runs nothing,
+// and neither ID can be reused meanwhile, so it counts as exited.
+const EXITED_STATE = /^[ZX]/;
+/** Whether the PID is a live process; a zombie is not one. */
 export function processExists(pid) {
+    let signalled = true;
     try {
         process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+        signalled = false;
+    }
+    if (process.platform !== "linux")
         return true;
+    try {
+        return !EXITED_STATE.test(linuxStatFields(readFileSync(`/proc/${pid}/stat`, "utf8"))[0] ?? "");
     }
     catch (error) {
-        return error.code === "EPERM";
+        if (!signalled || error.code !== "ENOENT")
+            return true;
+        // Reaped meanwhile, unless /proc hides a process we may signal (hidepid).
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (signalError) {
+            return signalError.code !== "ESRCH";
+        }
     }
 }
-export async function matchesProcessIdentity(pid, signature) {
-    if (!processExists(pid))
+/** Whether a PID signal 0 reaches is a darwin zombie; elsewhere processExists judges. */
+async function darwinZombie(pid) {
+    if (process.platform !== "darwin")
         return false;
-    if (!signature)
-        return false;
-    return await processBirthSignature(pid) === signature;
+    const { stdout } = await execFileAsync("ps", ["-o", "stat=", "-p", String(pid)]).catch(() => ({ stdout: "" }));
+    return EXITED_STATE.test(stdout.trim());
+}
+/** Whether /proc hides processes of other users (hidepid), so a scan may miss group members. */
+async function procHidesProcesses() {
+    const mounts = await readFile("/proc/self/mountinfo", "utf8");
+    return mounts.split("\n").some((line) => {
+        const [mount, filesystem] = line.split(" - ");
+        if (mount?.split(" ")[4] !== "/proc" || !filesystem)
+            return false;
+        return (filesystem.split(" ")[2] ?? "").split(",").some((option) => option.startsWith("hidepid=") && !["hidepid=0", "hidepid=off"].includes(option));
+    });
+}
+/**
+ * States of every member of a process group, or undefined when they cannot
+ * all be listed: an entry that cannot be read or parsed, or a /proc that
+ * hides processes, may be a live member.
+ */
+async function processGroupMemberStates(pgid) {
+    try {
+        if (process.platform === "linux") {
+            if (await procHidesProcesses())
+                return undefined;
+            const states = [];
+            for (const entry of await readdir("/proc")) {
+                if (!/^\d+$/.test(entry))
+                    continue;
+                const stat = await readFile(`/proc/${entry}/stat`, "utf8").catch((error) => {
+                    // Only a process that ended meanwhile may be skipped.
+                    if (error.code === "ENOENT")
+                        return undefined;
+                    throw error;
+                });
+                if (stat === undefined)
+                    continue;
+                const [state, , group] = linuxStatFields(stat);
+                if (!stat.includes(")") || !/^[A-Za-z]$/.test(state ?? "") || !/^\d+$/.test(group ?? ""))
+                    return undefined;
+                if (Number(group) === pgid)
+                    states.push(state);
+            }
+            return states;
+        }
+        if (process.platform === "darwin") {
+            const { stdout } = await execFileAsync("ps", ["-A", "-o", "pgid=,stat="]);
+            const rows = stdout.split("\n").filter((line) => line.trim()).map((line) => /^\s*(\d+)\s+(\S+)\s*$/.exec(line));
+            if (rows.some((row) => !row))
+                return undefined;
+            return rows.filter((row) => Number(row[1]) === pgid).map((row) => row[2]);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Only an absent PID or a readable birth signature that differs proves a
+ * recorded process is gone. A live PID whose recorded or current signature
+ * is unknown may still be that process.
+ */
+export function classifyProcessIdentity(exists, recorded, current) {
+    if (!exists)
+        return "exited";
+    if (!recorded || !current)
+        return "unverified";
+    if (current === recorded)
+        return "running";
+    // Signatures read in different formats cannot be compared.
+    return signatureFormat(current) === signatureFormat(recorded) ? "identity-mismatch" : "unverified";
+}
+function signatureFormat(signature) {
+    return signature.includes(":") ? signature.slice(0, signature.indexOf(":")) : "";
+}
+/** Allowance for wall-clock adjustment between a process start and its record. */
+const RECORD_CLOCK_TOLERANCE_MS = 2_000;
+/**
+ * Judge a live PID against a legacy darwin: signature. Earlier releases
+ * rendered its start time in the recording caller's time zone and locale,
+ * so neither an equal nor a different reading proves anything here. The
+ * record's own UTC time decides instead: DevFn writes it only after reading
+ * the signature of a live owner, so a process that started after it is a
+ * different process reusing the PID, and one that started no later was
+ * alive under that PID when the record was written and so is its owner.
+ * Without a record time, or within the clock tolerance, nothing is proven.
+ */
+export function classifyLegacyDarwinIdentity(pinnedStartTime, recordedAt) {
+    const start = pinnedStartTime === undefined ? undefined : parsePinnedStartTime(pinnedStartTime);
+    const recorded = typeof recordedAt === "string" ? Date.parse(recordedAt) : Number.NaN;
+    if (start === undefined || !Number.isFinite(recorded))
+        return "unverified";
+    if (start > recorded + RECORD_CLOCK_TOLERANCE_MS)
+        return "identity-mismatch";
+    return start <= recorded ? "running" : "unverified";
+}
+/**
+ * recordedAt is the UTC time the identity was recorded, after it was read
+ * from the live process; it decides only legacy darwin: signatures.
+ */
+export async function processIdentityStatus(pid, signature, recordedAt) {
+    if (!processExists(pid) || await darwinZombie(pid))
+        return "exited";
+    if (signature && process.platform === "darwin" && signatureFormat(signature) === "darwin") {
+        const start = await darwinStartTime(pid, { ...process.env, ...PINNED_PS_ENVIRONMENT }).catch(() => undefined);
+        return processExists(pid) ? classifyLegacyDarwinIdentity(start, recordedAt) : "exited";
+    }
+    const current = signature ? await processBirthSignature(pid) : undefined;
+    // A signature that cannot be read from a process that exited meanwhile is
+    // not an unverified owner.
+    if (signature && current === undefined && !processExists(pid))
+        return "exited";
+    return classifyProcessIdentity(true, signature, current);
+}
+/**
+ * Whether anything a recorded process group leader ran may still run. On
+ * POSIX the leader's PID is its group ID, and a PID is not reused while a
+ * group with that ID exists, so:
+ * - a reused PID ("identity-mismatch") proves the original group gone;
+ * - an exited leader whose group still has members is "unverified": those
+ *   members are what it started, unless the group was emptied and a later
+ *   process reusing the PID started another, which DevFn cannot tell apart;
+ * - only "exited" (leader and group gone, or only zombies left) and
+ *   "identity-mismatch" are death evidence. Windows has no process groups;
+ *   only the leader is judged.
+ */
+export async function processGroupStatus(pid, signature, recordedAt) {
+    const leader = await processIdentityStatus(pid, signature, recordedAt);
+    if (leader !== "exited" || process.platform === "win32")
+        return leader;
+    try {
+        process.kill(-pid, 0);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return "exited";
+        // macOS refuses to signal a group of only zombies; elsewhere a refusal
+        // means a member DevFn may not signal, which may be live.
+        if (code !== "EPERM" || process.platform !== "darwin")
+            return "unverified";
+    }
+    // Signal 0 also reaches zombies. The group is gone only when members are
+    // listed and every one has exited; one that cannot be listed may be live.
+    // Members reaped after the signal leave none to list, and so are gone too.
+    const states = await processGroupMemberStates(pid);
+    return states && states.every((state) => EXITED_STATE.test(state)) ? "exited" : "unverified";
+}
+/** Whether the PID is verifiably the recorded process, as required before signalling it. */
+export async function matchesProcessIdentity(pid, signature, recordedAt) {
+    return await processIdentityStatus(pid, signature, recordedAt) === "running";
 }

package/dist/schema.d.ts

@@ -1,3 +1,7 @@
-import type { DevFnConfig, DevFnPolicy } from "./types.js";
+import type { DevFnConfig, DevFnPolicy, ResourceSpec } from "./types.js";
+/** Normalized environment token of a resource or member name. */
+export declare function resourceToken(name: string): string;
+/** Every generated key a resource can emit, whichever target a profile selects. */
+export declare function resourceEnvironmentKeys(name: string, spec: ResourceSpec): string[];
 export declare function validateDevFnConfig(value: unknown): DevFnConfig;
 export declare function validateDevFnPolicy(value: unknown): DevFnPolicy;

package/dist/schema.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { DevFnConfigError } from "./errors.js";
-const SENSITIVE_KEY = /(authorization|token|secret|password|cookie|api[-_]?key|session[-_]?id|access[-_]?key|refresh[-_]?token)/i;
+import { isCredentialKey } from "./credentials.js";
 function fail(message, field) {
     throw new DevFnConfigError("DEVFN_CONFIG_INVALID", message, field);
 }
@@ -31,10 +31,25 @@ function stringArray(value, field) {
         fail(`${field} must be an array.`, field);
     return value.map((item, index) => string(item, `${field}[${index}]`));
 }
-function stringMap(value, field) {
+function stringMap(value, field, allowHost = false) {
     if (value === undefined)
         return undefined;
-    return Object.fromEntries(Object.entries(record(value, field)).map(([key, item]) => [key, string(item, `${field}.${key}`)]));
+    const seen = new Set();
+    return Object.fromEntries(Object.entries(record(value, field)).map(([key, item]) => {
+        environmentKey(key, `${field}.${key}`, allowHost);
+        if (seen.has(key.toUpperCase()))
+            fail(`${field} has colliding environment keys for ${key}.`, `${field}.${key}`);
+        seen.add(key.toUpperCase());
+        return [key, string(item, `${field}.${key}`)];
+    }));
+}
+function environmentKey(key, field, allowHost = false) {
+    if (!/^[A-Za-z_]\w*$/.test(key))
+        fail(`${field} must be an environment variable name.`, field);
+    if (["__proto__", "constructor", "prototype"].includes(key))
+        fail(`${field} is not a supported environment key.`, field);
+    if (key.toUpperCase().startsWith("DEVFN_") || (!allowHost && key.toUpperCase() === "HOST"))
+        fail(`${field} is reserved for DevFn startup.`, field);
 }
 function integer(value, field, min = 1, max = 65535) {
     if (!Number.isInteger(value) || value < min || value > max) {
@@ -120,21 +135,65 @@ function portSpec(value, field) {
         ...(optionalString(input.env, `${field}.env`) ? { env: optionalString(input.env, `${field}.env`) } : {}),
     };
 }
-function environmentFields(input, field) {
-    const env = stringMap(input.env, `${field}.env`);
-    const envAllowlist = stringArray(input.envAllowlist, `${field}.envAllowlist`);
-    const secretEnv = stringArray(input.secretEnv, `${field}.secretEnv`);
+function assertUniqueEnvironmentKeys(keys, field) {
+    const seen = new Set();
+    for (const key of keys ?? []) {
+        const folded = key.toUpperCase();
+        if (seen.has(folded))
+            fail(`${field} has colliding environment keys for ${key}.`, field);
+        seen.add(folded);
+    }
+}
+function assertSecretEnvironmentChannels(env, envAllowlist, secretEnv, field) {
     for (const key of Object.keys(env ?? {}))
-        if (SENSITIVE_KEY.test(key))
+        if (isCredentialKey(key))
             fail(`${field}.env.${key} must not contain a literal secret; inherit it through envAllowlist and declare it in secretEnv.`, `${field}.env.${key}`);
     for (const key of secretEnv ?? [])
         if (!envAllowlist?.includes(key))
             fail(`${field}.secretEnv contains ${key}, which is not present in envAllowlist.`, `${field}.secretEnv`);
     for (const key of envAllowlist ?? [])
-        if (SENSITIVE_KEY.test(key) && !secretEnv?.includes(key))
+        if (isCredentialKey(key) && !secretEnv?.includes(key))
             fail(`${field}.envAllowlist contains sensitive key ${key}; declare it in secretEnv for log redaction.`, `${field}.envAllowlist`);
+}
+function environmentFields(input, field, allowHost = false) {
+    const env = stringMap(input.env, `${field}.env`, allowHost);
+    const envAllowlist = stringArray(input.envAllowlist, `${field}.envAllowlist`);
+    const secretEnv = stringArray(input.secretEnv, `${field}.secretEnv`);
+    assertUniqueEnvironmentKeys(envAllowlist, `${field}.envAllowlist`);
+    assertUniqueEnvironmentKeys(secretEnv, `${field}.secretEnv`);
+    for (const key of envAllowlist ?? [])
+        environmentKey(key, `${field}.envAllowlist`, allowHost);
+    for (const key of secretEnv ?? [])
+        environmentKey(key, `${field}.secretEnv`, allowHost);
+    assertSecretEnvironmentChannels(env, envAllowlist, secretEnv, field);
     return { ...(env ? { env } : {}), ...(envAllowlist ? { envAllowlist } : {}), ...(secretEnv ? { secretEnv } : {}) };
 }
+function taskSpec(value, field) {
+    if (value === undefined)
+        return undefined;
+    const input = record(value, field);
+    const rerun = input.rerun === undefined ? "on-change" : string(input.rerun, `${field}.rerun`);
+    if (rerun !== "on-change" && rerun !== "always" && rerun !== "once")
+        fail(`${field}.rerun must be on-change, always or once.`, `${field}.rerun`);
+    const idempotent = optionalBoolean(input.idempotent, `${field}.idempotent`) ?? false;
+    const retries = input.retries === undefined ? 0 : integer(input.retries, `${field}.retries`, 0, 5);
+    if (rerun === "always" && !idempotent)
+        fail(`${field}.rerun always requires idempotent: true.`, `${field}.rerun`);
+    if (retries > 0 && !idempotent)
+        fail(`${field}.retries requires idempotent: true; a non-idempotent task is never repeated automatically.`, `${field}.retries`);
+    const inputs = uniqueNames(input.inputs, `${field}.inputs`)?.map((item, index) => relativePath(item, `${field}.inputs[${index}]`));
+    return {
+        rerun, idempotent, retries,
+        timeoutMs: input.timeoutMs === undefined ? 600_000 : integer(input.timeoutMs, `${field}.timeoutMs`, 1, 86_400_000),
+        ...(inputs ? { inputs } : {}),
+    };
+}
+/** A task serves nothing: no ports, readiness probe or persistence, and never public. */
+function assertFiniteTask(input, field, keys) {
+    for (const key of keys)
+        if (input[key] !== undefined)
+            fail(`${field}.${key} cannot be declared by a task; a task is ready when it exits successfully.`, `${field}.${key}`);
+}
 function processSpec(value, field) {
     const input = record(value, field);
     const adapter = string(input.adapter, `${field}.adapter`);
@@ -152,18 +211,26 @@ function processSpec(value, field) {
         fail(`${field}.exposure must be local or public.`, `${field}.exposure`);
     const ports = stringArray(input.ports, `${field}.ports`);
     const dependsOn = stringArray(input.dependsOn, `${field}.dependsOn`);
+    const resources = uniqueNames(input.resources, `${field}.resources`);
     const parsedHealth = health(input.health, `${field}.health`);
+    const task = taskSpec(input.task, `${field}.task`);
+    if (task)
+        assertFiniteTask(input, field, ["ports", "health"]);
+    if (task && exposure === "public")
+        fail(`${field}.exposure cannot be public for a task; a task serves nothing.`, `${field}.exposure`);
     return {
         adapter,
         exposure,
         ...(command ? { command } : {}),
         ...(script ? { script } : {}),
         ...(input.cwd === undefined ? {} : { cwd: relativePath(input.cwd, `${field}.cwd`) }),
-        ...environmentFields(input, field),
+        ...environmentFields(input, field, exposure === "public"),
         ...(ports ? { ports } : {}),
         ...(dependsOn ? { dependsOn } : {}),
+        ...(resources ? { resources } : {}),
         ...(parsedHealth ? { health: parsedHealth } : {}),
         ...(input.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: integer(input.shutdownTimeoutMs, `${field}.shutdownTimeoutMs`, 1, 3_600_000) }),
+        ...(task ? { task } : {}),
     };
 }
 function serviceSpec(value, field) {
@@ -172,7 +239,11 @@ function serviceSpec(value, field) {
         fail(`${field}.adapter must be compose.`, `${field}.adapter`);
     const ports = input.ports === undefined ? undefined : Object.fromEntries(Object.entries(record(input.ports, `${field}.ports`)).map(([name, internal]) => [name, integer(internal, `${field}.ports.${name}`)]));
     const dependsOn = stringArray(input.dependsOn, `${field}.dependsOn`);
+    const resources = uniqueNames(input.resources, `${field}.resources`);
     const parsedHealth = health(input.health, `${field}.health`);
+    const task = taskSpec(input.task, `${field}.task`);
+    if (task)
+        assertFiniteTask(input, field, ["ports", "health", "persistent"]);
     return {
         adapter: "compose",
         service: string(input.service, `${field}.service`),
@@ -180,9 +251,11 @@ function serviceSpec(value, field) {
         ...(optionalString(input.projectName, `${field}.projectName`) ? { projectName: optionalString(input.projectName, `${field}.projectName`) } : {}),
         ...(ports ? { ports } : {}),
         ...(dependsOn ? { dependsOn } : {}),
+        ...(resources ? { resources } : {}),
         ...(parsedHealth ? { health: parsedHealth } : {}),
         ...(input.persistent === undefined ? {} : { persistent: input.persistent === true }),
-        ...environmentFields(input, field),
+        ...environmentFields(input, field, true),
+        ...(task ? { task } : {}),
     };
 }
 function profileSpec(value, field) {
@@ -190,21 +263,63 @@ function profileSpec(value, field) {
     const environment = stringMap(input.environment, `${field}.environment`);
     const proxy = optionalBoolean(input.proxy, `${field}.proxy`);
     for (const key of Object.keys(environment ?? {}))
-        if (SENSITIVE_KEY.test(key))
+        if (isCredentialKey(key))
             fail(`${field}.environment.${key} must not contain a secret. Use process envAllowlist and secretEnv.`, `${field}.environment.${key}`);
+    const tunnel = input.tunnel === undefined ? undefined : profileTunnelSpec(input.tunnel, `${field}.tunnel`);
+    const resources = input.resources === undefined ? undefined : Object.fromEntries(Object.entries(record(input.resources, `${field}.resources`))
+        .map(([name, target]) => [name, string(target, `${field}.resources.${name}`)]));
     return {
         ...(stringArray(input.processes, `${field}.processes`) ? { processes: stringArray(input.processes, `${field}.processes`) } : {}),
         ...(stringArray(input.services, `${field}.services`) ? { services: stringArray(input.services, `${field}.services`) } : {}),
         ...(environment ? { environment } : {}),
         ...(proxy === undefined ? {} : { proxy }),
+        ...(tunnel ? { tunnel } : {}),
+        ...(resources ? { resources } : {}),
     };
 }
+function profileTunnelSpec(value, field) {
+    const input = record(value, field);
+    for (const key of Object.keys(input))
+        if (!["binding", "routes", "ephemeral"].includes(key))
+            fail(`${field}.${key} is not a tunnel field; credentials and provider accounts belong to the machine binding.`, `${field}.${key}`);
+    const binding = string(input.binding, `${field}.binding`);
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/.test(binding))
+        fail(`${field}.binding must be a registered tunnel binding name.`, `${field}.binding`);
+    const routes = stringArray(input.routes, `${field}.routes`) ?? [];
+    if (!routes.length || new Set(routes).size !== routes.length)
+        fail(`${field}.routes must name each public route once.`, `${field}.routes`);
+    const ephemeral = optionalBoolean(input.ephemeral, `${field}.ephemeral`);
+    return { binding, routes, ...(ephemeral ? { ephemeral } : {}) };
+}
 function hostnameSpec(value, field) {
     const input = record(value, field);
     const tls = input.tls === undefined ? "off" : string(input.tls, `${field}.tls`);
     if (tls !== "off" && tls !== "internal")
         fail(`${field}.tls must be off or internal.`, `${field}.tls`);
     const hostname = optionalString(input.hostname, `${field}.hostname`);
+    const domain = optionalString(input.domain, `${field}.domain`);
+    const host = optionalString(input.host, `${field}.host`);
+    // The generated alias adds a separator and a 22-character minimum
+    // worktree suffix; a longer host cannot fit in one DNS label.
+    if (host && (!domain || host.length > 40 || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(host)))
+        fail(`${field}.host requires a registered domain and one DNS label of at most 40 characters.`, `${field}.host`);
+    if (domain && hostname)
+        fail(`${field} cannot set both hostname and domain.`, field);
+    if (domain && (domain.length > 253 || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain) || domain.endsWith(".localhost"))) {
+        fail(`${field}.domain must be a concrete registered domain.`, `${field}.domain`);
+    }
+    if (domain && input.tls !== undefined)
+        fail(`${field}.tls is controlled by the machine domain registration; omit it from the manifest.`, `${field}.tls`);
+    const routePath = optionalString(input.path, `${field}.path`);
+    if (routePath && (!/^\/(?:[A-Za-z0-9._~!$&'()+,;=:@/-]*)$/.test(routePath) || routePath.includes("//") || routePath.split("/").some((part) => part === "." || part === ".."))) {
+        fail(`${field}.path must be an unambiguous absolute URL path.`, `${field}.path`);
+    }
+    const match = input.match === undefined ? undefined : string(input.match, `${field}.match`);
+    if (match && match !== "exact" && match !== "prefix")
+        fail(`${field}.match must be exact or prefix.`, `${field}.match`);
+    const stripPrefix = optionalBoolean(input.stripPrefix, `${field}.stripPrefix`);
+    if (stripPrefix && (match === "exact" || !routePath || routePath === "/"))
+        fail(`${field}.stripPrefix requires a non-root prefix path.`, `${field}.stripPrefix`);
     const expandedHostname = hostname?.replaceAll("{project}", "project").replaceAll("{instance}", "instance");
     if (hostname && (expandedHostname?.includes("{") || expandedHostname?.includes("}") || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+localhost$/i.test(expandedHostname))) {
         fail(`${field}.hostname must be a .localhost hostname using only {project} and {instance} placeholders.`, `${field}.hostname`);
@@ -212,10 +327,244 @@ function hostnameSpec(value, field) {
     return {
         target: string(input.target, `${field}.target`),
         ...(hostname ? { hostname } : {}),
-        tls,
+        ...(domain ? { domain } : {}),
+        ...(host ? { host } : {}),
+        ...(routePath ? { path: routePath } : {}),
+        ...(match ? { match: match } : {}),
+        ...(stripPrefix === undefined ? {} : { stripPrefix }),
+        ...(domain ? {} : { tls }),
         ...(stringArray(input.profiles, `${field}.profiles`) ? { profiles: stringArray(input.profiles, `${field}.profiles`) } : {}),
     };
 }
+function uniqueNames(value, field) {
+    const names = stringArray(value, field);
+    if (names && new Set(names).size !== names.length)
+        fail(`${field} must name each entry once.`, field);
+    return names;
+}
+const RESOURCE_KINDS = ["service", "database", "broker", "cache", "object-store", "browser"];
+const RESOURCE_NAME = /^[a-z][a-z0-9_-]{0,39}$/;
+const RESOURCE_MEMBER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const DATABASE_IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/;
+// An isolated namespace appends a separator and a 13-character owner token.
+const NAMESPACE_BASE = { database: /^[a-z][a-z0-9_]{0,48}$/, other: /^[a-z0-9][a-z0-9_-]{0,47}$/ };
+const DEFAULT_PORTS = { "http:": "80", "https:": "443", "ws:": "80", "wss:": "443" };
+/** Normalized environment token of a resource or member name. */
+export function resourceToken(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+/** Every generated key a resource can emit, whichever target a profile selects. */
+export function resourceEnvironmentKeys(name, spec) {
+    const prefix = `DEVFN_RESOURCE_${resourceToken(name)}_`;
+    const suffixes = [];
+    if (spec.kind !== "browser")
+        suffixes.push("HOST", "PORT", "ENDPOINT", "URL", "HOST_ENDPOINT", "INTERNAL_ENDPOINT");
+    if (spec.kind !== "service")
+        suffixes.push("NAMESPACE");
+    if (spec.kind === "database")
+        suffixes.push("DATABASE", ...(spec.namespace?.level === "schema" ? ["SCHEMA"] : []));
+    if (spec.kind === "cache" || spec.kind === "object-store")
+        suffixes.push("PREFIX");
+    if (spec.kind === "broker")
+        suffixes.push(...(spec.topics ?? []).map((topic) => `TOPIC_${resourceToken(topic)}`), "CONSUMER_GROUP");
+    if (spec.kind === "browser") {
+        suffixes.push(...(spec.cookies ?? []).map((cookie) => `COOKIE_${resourceToken(cookie)}`));
+        suffixes.push(...(spec.storageKeys ?? []).map((key) => `STORAGE_${resourceToken(key)}`));
+    }
+    return suffixes.map((suffix) => `${prefix}${suffix}`);
+}
+function resourceMembers(value, field) {
+    const names = uniqueNames(value, field);
+    const tokens = new Set();
+    for (const name of names ?? []) {
+        if (!RESOURCE_MEMBER.test(name))
+            fail(`${field} entries must use letters, numbers, underscores, and hyphens.`, field);
+        if (tokens.has(resourceToken(name)))
+            fail(`${field} has ambiguous names that normalize to ${resourceToken(name)}.`, field);
+        tokens.add(resourceToken(name));
+    }
+    return names;
+}
+function secretReferences(value, field) {
+    if (value === undefined)
+        return undefined;
+    return Object.fromEntries(Object.entries(record(value, field)).map(([name, environment]) => {
+        if (!/^[a-z][a-z0-9_]{0,39}$/.test(name))
+            fail(`${field}.${name} must be a lowercase secret field name.`, `${field}.${name}`);
+        const key = string(environment, `${field}.${name}`);
+        environmentKey(key, `${field}.${name}`);
+        return [name, key];
+    }));
+}
+function remoteResourceUrl(value, kind, field) {
+    const raw = string(value, field);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        fail(`${field} must be an absolute URL.`, field);
+    }
+    if (url.username || url.password)
+        fail(`${field} must not embed credentials; name them in secrets.`, field);
+    // Clients decode percent escapes, so an encoded assignment, query or
+    // userinfo would reach them as a credential. A target URL is only a host,
+    // port and plain path.
+    if (raw.includes("%"))
+        fail(`${field} must not contain percent-encoded data; name credentials in secrets.`, field);
+    if (url.search || url.hash || raw.includes("?") || raw.includes("#"))
+        fail(`${field} must not contain a query or fragment; add options in a template.`, field);
+    if (!url.hostname)
+        fail(`${field} requires a host.`, field);
+    if (!url.port && !DEFAULT_PORTS[url.protocol])
+        fail(`${field} requires an explicit port for ${url.protocol} targets.`, field);
+    if (/[=;@]/.test(url.pathname))
+        fail(`${field} path must not carry assignments or credentials.`, field);
+    if (kind === "database" && url.pathname && url.pathname !== "/")
+        fail(`${field} cannot name a database; the database comes from the resource namespace.`, field);
+    return raw;
+}
+function resourceTarget(value, kind, field) {
+    const input = record(value, field);
+    const secrets = secretReferences(input.secrets, `${field}.secrets`);
+    if (input.url !== undefined) {
+        for (const key of Object.keys(input))
+            if (!["url", "secrets"].includes(key))
+                fail(`${field}.${key} is not a remote target field.`, `${field}.${key}`);
+        return { url: remoteResourceUrl(input.url, kind, `${field}.url`), ...(secrets ? { secrets } : {}) };
+    }
+    for (const key of Object.keys(input))
+        if (!["node", "port", "scheme", "path", "secrets"].includes(key))
+            fail(`${field}.${key} is not a local target field.`, `${field}.${key}`);
+    const scheme = optionalString(input.scheme, `${field}.scheme`);
+    if (scheme && !/^[a-z][a-z0-9+.-]{0,31}$/.test(scheme))
+        fail(`${field}.scheme must be a URL scheme without "://".`, `${field}.scheme`);
+    const targetPath = optionalString(input.path, `${field}.path`);
+    if (targetPath && (!/^\/[A-Za-z0-9._~!$&'()+,:/-]*$/.test(targetPath) || targetPath.split("/").some((part) => part === "." || part === ".."))) {
+        fail(`${field}.path must be an absolute URL path without queries, assignments, or dot segments.`, `${field}.path`);
+    }
+    if (targetPath && kind === "database")
+        fail(`${field}.path cannot name a database; the database comes from the resource namespace.`, `${field}.path`);
+    return { node: string(input.node, `${field}.node`), port: string(input.port, `${field}.port`),
+        ...(scheme ? { scheme } : {}), ...(targetPath ? { path: targetPath } : {}), ...(secrets ? { secrets } : {}) };
+}
+function resourceNamespace(value, kind, field) {
+    if (value === undefined)
+        return undefined;
+    if (kind === "service")
+        fail(`${field} is unavailable for service resources.`, field);
+    const input = record(value, field);
+    for (const key of Object.keys(input))
+        if (!["base", "sharing", "level", "database"].includes(key))
+            fail(`${field}.${key} is not a namespace field.`, `${field}.${key}`);
+    const base = optionalString(input.base, `${field}.base`);
+    if (base && !NAMESPACE_BASE[kind === "database" ? "database" : "other"].test(base))
+        fail(`${field}.base is not a valid ${kind} namespace base.`, `${field}.base`);
+    const sharing = input.sharing === undefined ? undefined : string(input.sharing, `${field}.sharing`);
+    if (sharing !== undefined && sharing !== "isolated" && sharing !== "shared")
+        fail(`${field}.sharing must be isolated or shared.`, `${field}.sharing`);
+    const level = input.level === undefined ? undefined : string(input.level, `${field}.level`);
+    if (level !== undefined && (kind !== "database" || (level !== "database" && level !== "schema")))
+        fail(`${field}.level must be database or schema on a database resource.`, `${field}.level`);
+    const database = optionalString(input.database, `${field}.database`);
+    if ((level === "schema") !== (database !== undefined))
+        fail(`${field}.database is required exactly when level is schema.`, `${field}.database`);
+    if (database && !DATABASE_IDENTIFIER.test(database))
+        fail(`${field}.database must be a lowercase database identifier.`, `${field}.database`);
+    return { ...(base ? { base } : {}), ...(sharing ? { sharing: sharing } : {}),
+        ...(level ? { level: level } : {}), ...(database ? { database } : {}) };
+}
+function resourceSpec(value, field) {
+    const input = record(value, field);
+    const kind = string(input.kind, `${field}.kind`);
+    if (!RESOURCE_KINDS.includes(kind))
+        fail(`${field}.kind must be one of ${RESOURCE_KINDS.join(", ")}.`, `${field}.kind`);
+    const allowed = new Set(["kind", "targets", "defaultTarget", "namespace",
+        ...(kind === "broker" ? ["topics", "consumerGroup"] : []), ...(kind === "browser" ? ["cookies", "storageKeys"] : [])]);
+    for (const key of Object.keys(input))
+        if (!allowed.has(key))
+            fail(`${field}.${key} is not a field of ${kind} resources.`, `${field}.${key}`);
+    if (kind === "browser" && (input.targets !== undefined || input.defaultTarget !== undefined))
+        fail(`${field} browser metadata has no targets.`, field);
+    const targets = input.targets === undefined ? undefined : named(input.targets, `${field}.targets`, (item, itemField) => resourceTarget(item, kind, itemField));
+    if (kind !== "browser" && (!targets || !Object.keys(targets).length))
+        fail(`${field}.targets must declare at least one target.`, `${field}.targets`);
+    for (const name of Object.keys(targets ?? {}))
+        if (!RESOURCE_NAME.test(name))
+            fail(`${field}.targets.${name} must be a lowercase target name.`, `${field}.targets.${name}`);
+    const defaultTarget = optionalString(input.defaultTarget, `${field}.defaultTarget`);
+    if (defaultTarget && !Object.hasOwn(targets ?? {}, defaultTarget))
+        fail(`${field}.defaultTarget references unknown target ${defaultTarget}.`, `${field}.defaultTarget`);
+    const topics = resourceMembers(input.topics, `${field}.topics`);
+    if (kind === "broker" && !topics?.length)
+        fail(`${field}.topics must declare at least one topic.`, `${field}.topics`);
+    const consumerGroup = optionalString(input.consumerGroup, `${field}.consumerGroup`);
+    if (consumerGroup && !RESOURCE_MEMBER.test(consumerGroup))
+        fail(`${field}.consumerGroup must use letters, numbers, underscores, and hyphens.`, `${field}.consumerGroup`);
+    const cookies = resourceMembers(input.cookies, `${field}.cookies`);
+    const storageKeys = resourceMembers(input.storageKeys, `${field}.storageKeys`);
+    const namespace = resourceNamespace(input.namespace, kind, `${field}.namespace`);
+    return {
+        kind,
+        ...(targets ? { targets } : {}),
+        ...(defaultTarget ? { defaultTarget } : {}),
+        ...(namespace ? { namespace } : {}),
+        ...(topics ? { topics } : {}),
+        ...(consumerGroup ? { consumerGroup } : {}),
+        ...(cookies ? { cookies } : {}),
+        ...(storageKeys ? { storageKeys } : {}),
+    };
+}
+function validateLocalResourceTarget(config, target, field) {
+    const process = config.processes && Object.hasOwn(config.processes, target.node) ? config.processes[target.node] : undefined;
+    const service = config.services && Object.hasOwn(config.services, target.node) ? config.services[target.node] : undefined;
+    if (!process && !service)
+        fail(`${field}.node references unknown lifecycle node ${target.node}.`, `${field}.node`);
+    if (!config.ports || !Object.hasOwn(config.ports, target.port))
+        fail(`${field}.port references unknown port ${target.port}.`, `${field}.port`);
+    const declared = process ? process.ports?.includes(target.port) : service.ports?.[target.port] !== undefined;
+    if (!declared)
+        fail(`${field}.port ${target.port} is not an exposed port declared by ${target.node}.`, `${field}.port`);
+}
+function validateResourceReferences(config) {
+    const resources = config.resources ?? {};
+    const tokens = new Map();
+    const keys = new Map();
+    for (const [name, spec] of Object.entries(resources)) {
+        if (!RESOURCE_NAME.test(name))
+            fail(`resources.${name} must be a lowercase resource name.`, `resources.${name}`);
+        const prior = tokens.get(resourceToken(name));
+        if (prior)
+            fail(`resources.${prior} and resources.${name} are ambiguous: both normalize to ${resourceToken(name)}.`, `resources.${name}`);
+        tokens.set(resourceToken(name), name);
+        for (const key of resourceEnvironmentKeys(name, spec)) {
+            const owner = keys.get(key);
+            if (owner && owner !== name)
+                fail(`resources.${owner} and resources.${name} both emit ${key}.`, `resources.${name}`);
+            keys.set(key, name);
+        }
+        for (const [targetName, target] of Object.entries(spec.targets ?? {})) {
+            if ("node" in target)
+                validateLocalResourceTarget(config, target, `resources.${name}.targets.${targetName}`);
+        }
+    }
+    const consumers = [...Object.entries(config.processes ?? {}).map(([name, spec]) => [`processes.${name}`, spec.resources]),
+        ...Object.entries(config.services ?? {}).map(([name, spec]) => [`services.${name}`, spec.resources])];
+    for (const [field, consumed] of consumers) {
+        for (const resource of consumed ?? [])
+            if (!Object.hasOwn(resources, resource))
+                fail(`${field}.resources references unknown resource ${resource}.`, `${field}.resources`);
+    }
+    for (const [profileName, profile] of Object.entries(config.profiles)) {
+        for (const [resource, target] of Object.entries(profile.resources ?? {})) {
+            const field = `profiles.${profileName}.resources.${resource}`;
+            if (!Object.hasOwn(resources, resource))
+                fail(`${field} references unknown resource ${resource}.`, field);
+            if (!Object.hasOwn(resources[resource].targets ?? {}, target))
+                fail(`${field} references unknown target ${target}.`, field);
+        }
+    }
+}
 function prerequisites(value) {
     if (value === undefined)
         return undefined;
@@ -295,6 +644,21 @@ function validateSelectionReferences(config, ports, processes, services) {
         for (const service of profile.services ?? [])
             if (!services.has(service))
                 fail(`profiles.${name} references unknown service ${service}.`);
+        if (!profile.tunnel)
+            continue;
+        if (!profile.proxy)
+            fail(`profiles.${name}.tunnel requires proxy: true; public routes are served through the DevFn proxy.`, `profiles.${name}.tunnel`);
+        for (const route of profile.tunnel.routes) {
+            const hostname = config.hostnames?.[route];
+            if (!hostname || (hostname.profiles && !hostname.profiles.includes(name)))
+                fail(`profiles.${name}.tunnel.routes references ${route}, which is not a hostname route of this profile.`, `profiles.${name}.tunnel.routes`);
+            if (config.ports?.[hostname.target]?.protocol === "udp")
+                fail(`profiles.${name}.tunnel.routes cannot publish UDP port ${hostname.target}.`, `profiles.${name}.tunnel.routes`);
+            // The public hostname is <label>-<worktree>-<suffix>.<binding domain>, one DNS label under it.
+            const label = hostname.host ?? route;
+            if (label.length > 40 || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+                fail(`profiles.${name}.tunnel.routes: ${route} needs a lowercase DNS host label of at most 40 characters.`, `profiles.${name}.tunnel.routes`);
+        }
     }
     for (const [name, hostname] of Object.entries(config.hostnames ?? {})) {
         if (!ports.has(hostname.target))
@@ -327,19 +691,30 @@ function validateReferences(config) {
     validateProcessReferences(config, ports, nodes);
     validateServiceReferences(config, ports, nodes);
     validateSelectionReferences(config, ports, processes, services);
+    validateResourceReferences(config);
     const environmentOwners = new Map();
     for (const [name, spec] of Object.entries(config.ports ?? {})) {
-        if (spec.env?.startsWith("DEVFN_"))
+        if (spec.env?.toUpperCase().startsWith("DEVFN_"))
             fail(`ports.${name}.env cannot use reserved DEVFN_ runtime variables.`, `ports.${name}.env`);
+        if (spec.env)
+            environmentKey(spec.env, `ports.${name}.env`);
         const generated = `DEVFN_PORT_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
-        for (const environmentName of new Set([generated, ...(spec.env ? [spec.env] : [])])) {
-            const owner = environmentOwners.get(environmentName);
+        const generatedUrl = `DEVFN_URL_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+        for (const environmentName of new Set([generated, generatedUrl, ...(spec.env ? [spec.env] : [])])) {
+            const owner = environmentOwners.get(environmentName.toUpperCase());
             if (owner !== undefined && owner !== name)
                 fail(`Ports ${owner} and ${name} both emit environment variable ${environmentName}.`, `ports.${name}`);
-            environmentOwners.set(environmentName, name);
+            environmentOwners.set(environmentName.toUpperCase(), name);
         }
     }
     for (const [name, spec] of Object.entries(config.hostnames ?? {})) {
+        if (spec.domain) {
+            const label = spec.host ?? name;
+            if (label.length > 40 || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)) {
+                fail(`hostnames.${name} requires a registered-domain host label of at most 40 DNS-safe characters.`, `hostnames.${name}${spec.host ? ".host" : ""}`);
+            }
+            continue;
+        }
         const expanded = (spec.hostname ?? `${name}-{instance}.localhost`).replaceAll("{instance}", "instance").replaceAll("{project}", config.project.id);
         if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+localhost$/i.test(expanded))
             fail(`hostnames.${name}.hostname resolves to an invalid .localhost hostname for project ${config.project.id}.`, `hostnames.${name}.hostname`);
@@ -363,6 +738,7 @@ export function validateDevFnConfig(value) {
         ...(input.processes === undefined ? {} : { processes: named(input.processes, "processes", processSpec) }),
         ...(input.services === undefined ? {} : { services: named(input.services, "services", serviceSpec) }),
         ...(input.hostnames === undefined ? {} : { hostnames: named(input.hostnames, "hostnames", hostnameSpec) }),
+        ...(input.resources === undefined ? {} : { resources: named(input.resources, "resources", resourceSpec) }),
         ...(prerequisites(input.prerequisites) ? { prerequisites: prerequisites(input.prerequisites) } : {}),
         ...(environmentOutputs(input.environmentOutputs) ? { environmentOutputs: environmentOutputs(input.environmentOutputs) } : {}),
         ...(input.policy === undefined ? {} : { policy: relativePath(input.policy, "policy") }),
@@ -401,8 +777,10 @@ export function validateDevFnPolicy(value) {
         return input.ports.map((item, index) => policyEntry(item, `ports[${index}]`));
     })();
     const hostnameSuffix = optionalString(input.hostnameSuffix, "hostnameSuffix");
-    if (hostnameSuffix && (!hostnameSuffix.startsWith(".") || !hostnameSuffix.endsWith(".localhost")))
-        fail("hostnameSuffix must start with a dot and end in .localhost.", "hostnameSuffix");
+    // The shortest generated hostname adds a one-character route key and a
+    // 23-character "-o-<20 hex>" owner component, within 253 characters.
+    if (hostnameSuffix && (!/^\.(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*localhost$/i.test(hostnameSuffix) || hostnameSuffix.length > 229))
+        fail("hostnameSuffix must be a valid dot-prefixed .localhost suffix.", "hostnameSuffix");
     return {
         version: 1,
         ...(range(input.fallbackRange, "fallbackRange") ? { fallbackRange: range(input.fallbackRange, "fallbackRange") } : {}),

package/dist/trust.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { processBirthSignature, processExists } from "./process-identity.js";
+import { processBirthSignature, processIdentityStatus } from "./process-identity.js";
 export function defaultStateDir(env = process.env) {
     return env.XDG_STATE_HOME ? path.join(env.XDG_STATE_HOME, "devfn") : path.join(os.homedir(), ".local", "state", "devfn");
 }
@@ -35,12 +35,8 @@ async function staleTicket(filePath, ticket, staleMs) {
         return false;
     if (!ticket?.pid)
         return true;
-    if (!processExists(ticket.pid))
-        return true;
-    if (!ticket.birthSignature)
-        return false;
-    const currentSignature = await processBirthSignature(ticket.pid);
-    return currentSignature !== undefined && currentSignature !== ticket.birthSignature;
+    const owner = await processIdentityStatus(ticket.pid, ticket.birthSignature, ticket.createdAt);
+    return owner === "exited" || owner === "identity-mismatch";
 }
 async function ticketPaths(lockPath) {
     return (await readdir(lockPath)).filter((name) => name.endsWith(".choosing") || name.endsWith(".ticket")).map((name) => path.join(lockPath, name));

package/dist/types.d.ts

@@ -30,6 +30,32 @@ export interface PortSpec {
     block?: string;
     env?: string;
 }
+/**
+ * A finite lifecycle node: it runs to completion instead of serving, and
+ * only its successful exit (code 0) lets dependents start. A task declares
+ * no ports or health check and is never a resource target provider.
+ */
+export interface TaskSpec {
+    /**
+     * When a later start runs it again: "on-change" (default) when no success
+     * is recorded for its current input revision, "always" on every start
+     * (requires idempotent), "once" never after a success, failing before any
+     * mutation when its input revision changed.
+     */
+    rerun?: "on-change" | "always" | "once";
+    /**
+     * Repeating it, also after an attempt that may have partly applied, is
+     * safe. Without it a failed, timed-out, cancelled or interrupted attempt
+     * blocks later starts until the task is explicitly rerun. Defaults to false.
+     */
+    idempotent?: boolean;
+    /** Further attempts within one start after a failed or timed-out one; requires idempotent. 0-5, defaults to 0. */
+    retries?: number;
+    /** Per-attempt limit after which the task is stopped. Defaults to 600000. */
+    timeoutMs?: number;
+    /** Repository-relative files and directories whose content is part of the input revision. */
+    inputs?: string[];
+}
 export interface ProcessSpec {
     adapter: RuntimeAdapter;
     exposure?: "local" | "public";
@@ -41,8 +67,12 @@ export interface ProcessSpec {
     secretEnv?: string[];
     ports?: string[];
     dependsOn?: string[];
+    /** Resources this node consumes; a selected local target starts before it. */
+    resources?: string[];
     health?: HealthCheck;
     shutdownTimeoutMs?: number;
+    /** Run as a finite task instead of a daemon. */
+    task?: TaskSpec;
 }
 export interface ComposeServiceSpec {
     adapter: "compose";
@@ -51,21 +81,63 @@ export interface ComposeServiceSpec {
     projectName?: string;
     ports?: Record<string, number>;
     dependsOn?: string[];
+    /** Resources this node consumes; a selected local target starts before it. */
+    resources?: string[];
     health?: HealthCheck;
     persistent?: boolean;
     env?: Record<string, string>;
     envAllowlist?: string[];
     secretEnv?: string[];
+    /** Run the service's command once in a one-off container (docker compose run) as a finite task. */
+    task?: TaskSpec;
+}
+/**
+ * Routes a profile publishes through a machine-registered public tunnel
+ * binding. Selecting it never authorizes exposure: every start still needs
+ * --allow-public.
+ */
+export interface ProfileTunnelSpec {
+    /** Name of a machine tunnel binding registered to this repository and project. */
+    binding: string;
+    /** Keys of `hostnames` entries selected by this profile; only these are public. */
+    routes: string[];
+    /**
+     * Explicitly select a binding whose provider assigns public URLs only after
+     * its connector starts (ngrok ephemeral endpoints). Those URLs reach the
+     * receipt and tunnel status, never a pre-start template reference.
+     */
+    ephemeral?: boolean;
 }
 export interface ProfileSpec {
     processes?: string[];
     services?: string[];
     environment?: Record<string, string>;
     proxy?: boolean;
+    tunnel?: ProfileTunnelSpec;
+    /** Selected target name by resource; overrides the resource's defaultTarget. */
+    resources?: Record<string, string>;
 }
+/**
+ * A proxy route. Validation accepts two variants: a .localhost route
+ * (optional `hostname` template and `tls`) or a registered-domain route
+ * (`domain`, optional `host`, TLS from the machine registration). `domain`
+ * excludes `hostname` and `tls`; `host` requires `domain`.
+ */
 export interface HostnameSpec {
     target: string;
+    /** .localhost hostname template using {project} and {instance}; excludes domain. */
     hostname?: string;
+    /** Machine-registered domain; a manifest cannot create the registration. */
+    domain?: string;
+    /** Registered-domain host label; defaults to the route key. Requires domain. */
+    host?: string;
+    /** Absolute URL path; defaults to "/". */
+    path?: string;
+    /** Defaults to "prefix". */
+    match?: "exact" | "prefix";
+    /** Strip the path prefix upstream; requires a non-root prefix path. Defaults to false. */
+    stripPrefix?: boolean;
+    /** .localhost routes only; defaults to "off". */
     tls?: "off" | "internal";
     profiles?: string[];
 }
@@ -80,6 +152,51 @@ export interface EnvironmentOutput {
     format?: "dotenv" | "json";
     mode?: number;
 }
+export type ResourceKind = "service" | "database" | "broker" | "cache" | "object-store" | "browser";
+/**
+ * A resource target. A local target names the lifecycle node and declared
+ * port that provide it; a remote target names a credential-free URL. Secret
+ * fields name host environment variables, never values.
+ */
+export type ResourceTargetSpec = {
+    node: string;
+    port: string;
+    scheme?: string;
+    path?: string;
+    secrets?: Record<string, string>;
+} | {
+    url: string;
+    secrets?: Record<string, string>;
+};
+/**
+ * Isolated namespaces append an opaque runtime-owner token; shared namespaces
+ * use `base` unchanged across runtimes. Sharing is never implied.
+ */
+export interface ResourceNamespaceSpec {
+    /** Defaults to the resource name. */
+    base?: string;
+    /** Defaults to "isolated". */
+    sharing?: "isolated" | "shared";
+    /** Database resources: namespace the database (default) or a schema in `database`. */
+    level?: "database" | "schema";
+    /** Fixed database containing namespaced schemas; requires level "schema". */
+    database?: string;
+}
+export interface ResourceSpec {
+    kind: ResourceKind;
+    /** Required for every kind except browser. */
+    targets?: Record<string, ResourceTargetSpec>;
+    defaultTarget?: string;
+    namespace?: ResourceNamespaceSpec;
+    /** Broker topics; each receives a namespaced name. */
+    topics?: string[];
+    /** Broker consumer group suffix; the group shares the topics' namespace. */
+    consumerGroup?: string;
+    /** Browser cookie names that receive namespaced names. */
+    cookies?: string[];
+    /** Browser storage keys that receive namespaced names. */
+    storageKeys?: string[];
+}
 export interface DevFnConfig {
     version: 1;
     project: {
@@ -93,6 +210,7 @@ export interface DevFnConfig {
     services?: Record<string, ComposeServiceSpec>;
     profiles: Record<string, ProfileSpec>;
     hostnames?: Record<string, HostnameSpec>;
+    resources?: Record<string, ResourceSpec>;
     prerequisites?: RuntimePrerequisite[];
     environmentOutputs?: EnvironmentOutput[];
     policy?: string;

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "@devfn/config",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Validated project manifests, organization policies, discovery, and trust contracts for DevFn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/superfunctions.git",
+    "directory": "devfn/config"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist", "README.md"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -14,8 +27,17 @@
     "lint": "echo 'lint not configured'",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
-  "dependencies": { "@clifn/core": "0.1.0", "@types/node": "^22.0.0", "typescript": "^5.6.0" },
-  "devDependencies": { "vitest": "^3.2.4" },
-  "engines": { "node": ">=22" },
-  "license": "MIT"
+  "dependencies": {
+    "@clifn/core": "0.1.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "gitHead": "699d9d09932199d660333c57fe7bc646492ea3bf"
 }