@flash-dns/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imba97 <https://github.com/imba97>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @flash-dns/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DNS naming, configuration and ownership-aware reconciliation.
+
+ESM, Node.js >=22.14.0.
+
+See the [project documentation](https://github.com/flash-tunnel/flash-dns#readme) for configuration, SDK examples and ownership semantics.
+
+MIT License.

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+import { DnsConfig } from '@flash-dns/config';
+import { DesiredRecord, OperationContext, Zone, DnsRecord, RecordRef, DnsAdapter } from '@flash-dns/types';
+
+declare function findConfigFile(cwd: string): string | undefined;
+declare function validateConfig(config: unknown): asserts config is DnsConfig;
+declare function loadDnsConfig(cwd: string, explicit?: string): Promise<{
+    config: DnsConfig;
+    source?: string;
+    configDir: string;
+}>;
+interface CliOverrides {
+    provider?: string;
+    zone?: string;
+    hostname?: string;
+    project?: string;
+    projectId?: string;
+    template?: string;
+    type?: string;
+    content?: string;
+    ttl?: string | number;
+    zoneId?: string;
+    proxied?: boolean;
+    branch?: string;
+    session?: string;
+}
+interface ResolvedDnsConfig {
+    provider: string;
+    zone: string;
+    hostname: string;
+    projectId?: string;
+    type?: string;
+    content?: string;
+    ttl?: number | 'auto';
+    proxied?: boolean;
+    zoneId?: string;
+    sources: Record<string, string>;
+    configDir: string;
+}
+declare function resolveDnsConfig(input: {
+    cwd: string;
+    config: DnsConfig;
+    configFile?: string;
+    env?: Record<string, string | undefined>;
+    cli?: CliOverrides;
+}): ResolvedDnsConfig;
+declare function desiredFromConfig(config: ReturnType<typeof resolveDnsConfig>): DesiredRecord<{
+    proxied?: boolean;
+}>;
+
+interface DnsPlan<P = Record<string, unknown>> {
+    operation: 'create' | 'update' | 'noop' | 'conflict';
+    zone: Zone;
+    desired: DesiredRecord<P>;
+    existing?: DnsRecord<P>;
+    conflict?: {
+        code: 'RECORD_CONFLICT' | 'OWNERSHIP_MISMATCH' | 'AMBIGUOUS_RECORD';
+        message: string;
+    };
+}
+interface EnsureResult<P = Record<string, unknown>> {
+    action: 'created' | 'updated' | 'unchanged';
+    record: DnsRecord<P>;
+    ref: RecordRef;
+}
+interface RemoveResult {
+    action: 'removed' | 'already-absent';
+}
+interface DnsManager<P = Record<string, unknown>> {
+    plan: (input: DesiredRecord<P>, context?: OperationContext) => Promise<DnsPlan<P>>;
+    ensure: (input: DesiredRecord<P>, context?: OperationContext) => Promise<EnsureResult<P>>;
+    remove: (target: RecordRef, context?: OperationContext) => Promise<RemoveResult>;
+}
+declare function createDnsManager<P extends object>(options: {
+    adapter: DnsAdapter<P>;
+}): DnsManager<P>;
+
+declare function normalizeProjectName(input: string): string;
+declare function validateLabel(label: string): string;
+declare function normalizeHostname(input: string, wildcard?: boolean): string;
+declare function assertInZone(hostname: string, zone: string): void;
+declare function renderHostname(template: string, variables: Record<string, string | undefined>): string;
+declare function normalizeContent(type: string, content: string): string;
+
+export { assertInZone, createDnsManager, desiredFromConfig, findConfigFile, loadDnsConfig, normalizeContent, normalizeHostname, normalizeProjectName, renderHostname, resolveDnsConfig, validateConfig, validateLabel };
+export type { CliOverrides, DnsManager, DnsPlan, EnsureResult, RemoveResult, ResolvedDnsConfig };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { DnsConfig } from '@flash-dns/config';
+import { DesiredRecord, OperationContext, Zone, DnsRecord, RecordRef, DnsAdapter } from '@flash-dns/types';
+
+declare function findConfigFile(cwd: string): string | undefined;
+declare function validateConfig(config: unknown): asserts config is DnsConfig;
+declare function loadDnsConfig(cwd: string, explicit?: string): Promise<{
+    config: DnsConfig;
+    source?: string;
+    configDir: string;
+}>;
+interface CliOverrides {
+    provider?: string;
+    zone?: string;
+    hostname?: string;
+    project?: string;
+    projectId?: string;
+    template?: string;
+    type?: string;
+    content?: string;
+    ttl?: string | number;
+    zoneId?: string;
+    proxied?: boolean;
+    branch?: string;
+    session?: string;
+}
+interface ResolvedDnsConfig {
+    provider: string;
+    zone: string;
+    hostname: string;
+    projectId?: string;
+    type?: string;
+    content?: string;
+    ttl?: number | 'auto';
+    proxied?: boolean;
+    zoneId?: string;
+    sources: Record<string, string>;
+    configDir: string;
+}
+declare function resolveDnsConfig(input: {
+    cwd: string;
+    config: DnsConfig;
+    configFile?: string;
+    env?: Record<string, string | undefined>;
+    cli?: CliOverrides;
+}): ResolvedDnsConfig;
+declare function desiredFromConfig(config: ReturnType<typeof resolveDnsConfig>): DesiredRecord<{
+    proxied?: boolean;
+}>;
+
+interface DnsPlan<P = Record<string, unknown>> {
+    operation: 'create' | 'update' | 'noop' | 'conflict';
+    zone: Zone;
+    desired: DesiredRecord<P>;
+    existing?: DnsRecord<P>;
+    conflict?: {
+        code: 'RECORD_CONFLICT' | 'OWNERSHIP_MISMATCH' | 'AMBIGUOUS_RECORD';
+        message: string;
+    };
+}
+interface EnsureResult<P = Record<string, unknown>> {
+    action: 'created' | 'updated' | 'unchanged';
+    record: DnsRecord<P>;
+    ref: RecordRef;
+}
+interface RemoveResult {
+    action: 'removed' | 'already-absent';
+}
+interface DnsManager<P = Record<string, unknown>> {
+    plan: (input: DesiredRecord<P>, context?: OperationContext) => Promise<DnsPlan<P>>;
+    ensure: (input: DesiredRecord<P>, context?: OperationContext) => Promise<EnsureResult<P>>;
+    remove: (target: RecordRef, context?: OperationContext) => Promise<RemoveResult>;
+}
+declare function createDnsManager<P extends object>(options: {
+    adapter: DnsAdapter<P>;
+}): DnsManager<P>;
+
+declare function normalizeProjectName(input: string): string;
+declare function validateLabel(label: string): string;
+declare function normalizeHostname(input: string, wildcard?: boolean): string;
+declare function assertInZone(hostname: string, zone: string): void;
+declare function renderHostname(template: string, variables: Record<string, string | undefined>): string;
+declare function normalizeContent(type: string, content: string): string;
+
+export { assertInZone, createDnsManager, desiredFromConfig, findConfigFile, loadDnsConfig, normalizeContent, normalizeHostname, normalizeProjectName, renderHostname, resolveDnsConfig, validateConfig, validateLabel };
+export type { CliOverrides, DnsManager, DnsPlan, EnsureResult, RemoveResult, ResolvedDnsConfig };

package/dist/index.mjs

@@ -0,0 +1,391 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve, join, dirname, parse, basename } from 'node:path';
+import process from 'node:process';
+import { DnsError, checkAborted, sameOwner } from '@flash-dns/types';
+import { createJiti } from 'jiti';
+import { loadConfig } from 'unconfig';
+import { isIP } from 'node:net';
+
+function normalizeProjectName(input) {
+  return validateLabel(input.replace(/^@/, "").replaceAll("/", "-").toLowerCase());
+}
+function validateLabel(label) {
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+    throw new DnsError("NAME_INVALID", `Invalid DNS label: ${label}`);
+  return label;
+}
+function normalizeHostname(input, wildcard = false) {
+  if (typeof input !== "string")
+    throw new DnsError("NAME_INVALID", "Hostname must be a string");
+  const name = input.toLowerCase().replace(/\.$/, "");
+  const labels = (wildcard && name.startsWith("*.") ? name.slice(2) : name).split(".");
+  if (!name || name.length > 253)
+    throw new DnsError("NAME_INVALID", "Hostname must contain 1\u2013253 ASCII characters");
+  labels.forEach(validateLabel);
+  return name;
+}
+function assertInZone(hostname, zone) {
+  if (hostname !== zone && !hostname.endsWith(`.${zone}`))
+    throw new DnsError("NAME_INVALID", `Hostname ${hostname} is outside Zone ${zone}`);
+}
+function renderHostname(template, variables) {
+  const result = template.replace(/\{([^{}]+)\}/g, (_, key) => {
+    const value = variables[key];
+    if (value === void 0 || value === "")
+      throw new DnsError("TEMPLATE_VARIABLE_MISSING", `Missing template variable: ${key}`);
+    return validateLabel(value.toLowerCase());
+  });
+  return normalizeHostname(result, true);
+}
+function normalizeContent(type, content) {
+  if (typeof content !== "string" || content.length === 0)
+    throw new DnsError("CONFIG_INVALID", "record.content must be a non-empty string");
+  if (type === "A" && isIP(content) !== 4 || type === "AAAA" && isIP(content) !== 6)
+    throw new DnsError("CONFIG_INVALID", `Invalid ${type} address`);
+  if (type === "AAAA")
+    return new URL(`http://[${content}]/`).hostname.slice(1, -1);
+  return type === "CNAME" ? normalizeHostname(content) : content;
+}
+
+const require$1 = createRequire(import.meta.url);
+const filenames = ["ts", "mts", "js", "mjs", "json"].map((ext) => `flash-dns.config.${ext}`);
+function findConfigFile(cwd) {
+  let dir = resolve(cwd);
+  while (true) {
+    for (const filename of filenames) {
+      const candidate = join(dir, filename);
+      if (existsSync(candidate))
+        return candidate;
+    }
+    if (existsSync(join(dir, ".git")) || dirname(dir) === dir)
+      return void 0;
+    dir = dirname(dir);
+  }
+}
+function object(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new DnsError("CONFIG_INVALID", `${path} must be an object`);
+}
+function validateConfig(config) {
+  object(config, "config");
+  const schema = {
+    provider: "string",
+    zone: "string",
+    hostname: "string",
+    project: { name: "string", id: "string" },
+    naming: { template: "string" },
+    variables: "variables",
+    record: { type: "string", content: "string", ttl: "ttl" },
+    providers: { cloudflare: { zoneId: "string", proxied: "boolean" } }
+  };
+  function visit(value, fields, path) {
+    for (const [key, item] of Object.entries(value)) {
+      const spec = fields[key];
+      const field = `${path}.${key}`;
+      if (!spec)
+        throw new DnsError("CONFIG_INVALID", `Unknown field: ${field}`);
+      if (item === void 0)
+        continue;
+      if (typeof spec === "object") {
+        object(item, field);
+        visit(item, spec, field);
+      } else if (spec === "variables") {
+        object(item, field);
+        if (Object.values(item).some((v) => typeof v !== "string"))
+          throw new DnsError("CONFIG_INVALID", `${field} values must be strings`);
+      } else if (spec === "ttl" ? item !== "auto" && (!Number.isInteger(item) || Number(item) <= 0) : spec === "boolean" ? typeof item !== "boolean" : typeof item !== "string") {
+        throw new DnsError("CONFIG_INVALID", `Invalid value for ${field}`);
+      }
+    }
+  }
+  visit(config, schema, "config");
+}
+async function loadDnsConfig(cwd, explicit) {
+  const source = explicit ? resolve(cwd, explicit) : findConfigFile(cwd);
+  if (!source)
+    return { config: {}, configDir: resolve(cwd) };
+  if (!existsSync(source))
+    throw new DnsError("CONFIG_INVALID", `Config file not found: ${source}`);
+  try {
+    const file = parse(source);
+    const configModule = require$1.resolve("@flash-dns/config");
+    const jiti = createJiti(import.meta.url, {
+      fsCache: false,
+      moduleCache: false,
+      alias: {
+        "flash-dns/config": configModule,
+        "flash-dns": configModule,
+        "@flash-dns/config": configModule
+      }
+    });
+    const loaded = await loadConfig({
+      cwd: file.dir,
+      merge: false,
+      sources: [{
+        files: file.name,
+        extensions: [file.ext.slice(1)],
+        parser: file.ext === ".json" ? "json" : (filepath) => jiti.import(filepath, { default: true })
+      }]
+    });
+    validateConfig(loaded.config);
+    return { config: loaded.config, source, configDir: file.dir };
+  } catch (cause) {
+    throw new DnsError("CONFIG_INVALID", `Invalid configuration: ${source}`, {
+      hint: cause instanceof DnsError ? cause.message : "Check the configuration syntax and imports",
+      cause
+    });
+  }
+}
+function resolveDnsConfig(input) {
+  validateConfig(input.config);
+  const config = input.config;
+  const cli = input.cli ?? {};
+  const env = input.env ?? process.env;
+  const sources = {};
+  function pick(path, cliValue, envValue, fileValue, fallback) {
+    for (const [source, value] of [["cli", cliValue], ["env", envValue], ["config", fileValue], ["default", fallback]]) {
+      if (value !== void 0) {
+        sources[path] = source;
+        return value;
+      }
+    }
+  }
+  const provider = pick("provider", cli.provider, env.FLASH_DNS_PROVIDER, config.provider, "cloudflare");
+  if (provider !== "cloudflare")
+    throw new DnsError("CAPABILITY_UNSUPPORTED", "CLI currently supports only cloudflare");
+  const zoneValue = pick("zone", cli.zone, env.FLASH_DNS_ZONE, config.zone);
+  if (!zoneValue)
+    throw new DnsError("CONFIG_INVALID", "zone is required");
+  const zone = normalizeHostname(zoneValue);
+  const configDir = input.configFile ? dirname(input.configFile) : resolve(input.cwd);
+  const projectId = pick("project.id", cli.projectId, env.FLASH_DNS_PROJECT_ID, config.project?.id);
+  const template = pick("naming.template", cli.template, env.FLASH_DNS_TEMPLATE, config.naming?.template, `{project}.${zone}`);
+  let hostname = pick("hostname", cli.hostname, env.FLASH_DNS_HOSTNAME, config.hostname);
+  if (!hostname) {
+    const variables = { ...config.variables };
+    if (template.includes("{project}")) {
+      let project = pick("project.name", cli.project, env.FLASH_DNS_PROJECT, config.project?.name);
+      if (project === void 0) {
+        const packageFile = join(configDir, "package.json");
+        if (existsSync(packageFile)) {
+          try {
+            const pkg = JSON.parse(readFileSync(packageFile, "utf8"));
+            if (pkg.name !== void 0 && typeof pkg.name !== "string")
+              throw new Error("Invalid name");
+            project = pkg.name;
+            sources["project.name"] = packageFile;
+          } catch {
+            throw new DnsError("CONFIG_INVALID", `Invalid package.json: ${packageFile}`);
+          }
+        }
+        project ??= basename(configDir);
+        sources["project.name"] ??= "directory";
+      }
+      variables.project = normalizeProjectName(project);
+    }
+    if (template.includes("{branch}")) {
+      variables.branch = cli.branch ?? env.FLASH_DNS_BRANCH ?? variables.branch;
+      if (variables.branch === void 0) {
+        try {
+          variables.branch = execFileSync("git", ["branch", "--show-current"], { cwd: input.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        } catch {
+          throw new DnsError("TEMPLATE_VARIABLE_MISSING", "branch must be provided outside a Git checkout");
+        }
+      }
+    }
+    variables.session = cli.session ?? env.FLASH_DNS_SESSION ?? variables.session;
+    hostname = renderHostname(template, variables);
+  }
+  hostname = normalizeHostname(hostname, true);
+  assertInZone(hostname, zone);
+  const rawTtl = pick("record.ttl", cli.ttl, env.FLASH_DNS_TTL, config.record?.ttl);
+  const ttl = rawTtl === void 0 ? void 0 : rawTtl === "auto" ? "auto" : Number(rawTtl);
+  if (ttl !== void 0 && ttl !== "auto" && (!Number.isInteger(ttl) || ttl <= 0))
+    throw new DnsError("CONFIG_INVALID", "record.ttl must be auto or a positive integer");
+  const rawProxy = env.FLASH_DNS_PROXIED;
+  if (cli.proxied === void 0 && rawProxy !== void 0 && rawProxy !== "true" && rawProxy !== "false")
+    throw new DnsError("CONFIG_INVALID", "FLASH_DNS_PROXIED must be true or false");
+  const proxied = pick("providers.cloudflare.proxied", cli.proxied, rawProxy === void 0 ? void 0 : rawProxy === "true", config.providers?.cloudflare?.proxied);
+  const type = pick("record.type", cli.type, env.FLASH_DNS_TYPE, config.record?.type);
+  if (type !== void 0 && !["A", "AAAA", "CNAME", "TXT"].includes(type))
+    throw new DnsError("CONFIG_INVALID", "record.type must be A, AAAA, CNAME or TXT");
+  return {
+    provider,
+    zone,
+    hostname,
+    projectId,
+    type,
+    content: pick("record.content", cli.content, env.FLASH_DNS_CONTENT, config.record?.content),
+    ttl,
+    proxied,
+    zoneId: pick("providers.cloudflare.zoneId", cli.zoneId, env.CLOUDFLARE_ZONE_ID, config.providers?.cloudflare?.zoneId),
+    sources,
+    configDir
+  };
+}
+function desiredFromConfig(config) {
+  if (!config.projectId || !config.type || config.content === void 0)
+    throw new DnsError("CONFIG_INVALID", "project.id, record.type and record.content are required; run init or supply explicit values");
+  return {
+    zone: config.zone,
+    name: config.hostname,
+    type: config.type,
+    content: config.content,
+    owner: { application: "flash-dns", id: config.projectId },
+    ttl: config.ttl,
+    providerOptions: config.proxied === void 0 ? {} : { proxied: config.proxied }
+  };
+}
+
+function fingerprint(value) {
+  return JSON.stringify(value, (_, item) => {
+    if (item && typeof item === "object" && !Array.isArray(item))
+      return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)));
+    return item;
+  });
+}
+function createDnsManager(options) {
+  const { adapter } = options;
+  const methods = ["resolveZone", "listRecords", "getRecord", "createRecord", "updateRecord", "deleteRecord"];
+  const caps = adapter?.capabilities;
+  if (!adapter || adapter.apiVersion !== 1 || methods.some((method) => typeof adapter[method] !== "function") || !caps || !Array.isArray(caps.recordTypes) || !Array.isArray(caps.extensions) || !caps.ttl || typeof caps.update !== "boolean" || typeof caps.wildcard !== "boolean" || typeof caps.lookupByName !== "boolean") {
+    throw new DnsError("ADAPTER_INCOMPATIBLE", "Adapter must implement the v1 contract");
+  }
+  const locks = /* @__PURE__ */ new Map();
+  async function locked(key, execute) {
+    const previous = locks.get(key) ?? Promise.resolve();
+    const next = previous.catch(() => {
+    }).then(execute);
+    locks.set(key, next);
+    try {
+      return await next;
+    } finally {
+      if (locks.get(key) === next)
+        locks.delete(key);
+    }
+  }
+  function normalize(input) {
+    const name = normalizeHostname(input.name, true);
+    const zone = normalizeHostname(input.zone);
+    assertInZone(name, zone);
+    const caps2 = adapter.capabilities;
+    if (!caps2.recordTypes.includes(input.type) || caps2.ownership !== "metadata" || !caps2.lookupByName || name.startsWith("*.") && !caps2.wildcard) {
+      throw new DnsError("CAPABILITY_UNSUPPORTED", "Adapter does not support the requested record or ownership");
+    }
+    if (!input.owner?.application?.trim() || !input.owner.id?.trim())
+      throw new DnsError("CONFIG_INVALID", "A stable owner.application and owner.id are required");
+    if (input.ttl !== void 0 && (input.ttl === "auto" ? !caps2.ttl.auto : !Number.isInteger(input.ttl) || input.ttl < caps2.ttl.min || input.ttl > caps2.ttl.max)) {
+      throw new DnsError("CAPABILITY_UNSUPPORTED", "Unsupported TTL");
+    }
+    if (Object.keys(input.providerOptions ?? {}).some((key) => !caps2.extensions.includes(key)))
+      throw new DnsError("CAPABILITY_UNSUPPORTED", "Unsupported provider option");
+    const desired = { ...input, name, zone, content: normalizeContent(input.type, input.content) };
+    return adapter.normalizeDesired?.(desired) ?? desired;
+  }
+  function matches(record, desired) {
+    return normalizeHostname(record.name, true) === desired.name && record.type === desired.type && normalizeContent(record.type, record.content) === desired.content && sameOwner(record.ownership, desired.owner) && (desired.ttl === void 0 || record.ttl === desired.ttl) && Object.entries(desired.providerOptions ?? {}).every(([key, value]) => record.providerOptions?.[key] === value);
+  }
+  async function plan(input, context) {
+    checkAborted(context);
+    let desired = normalize(input);
+    const zone = await adapter.resolveZone(desired.zone, context);
+    assertInZone(desired.name, normalizeHostname(zone.name));
+    const records = (await adapter.listRecords(zone.id, desired.name, context)).filter((record) => normalizeHostname(record.name, true) === desired.name);
+    const base = { zone, desired };
+    const conflict = (code, message) => ({
+      ...base,
+      operation: "conflict",
+      conflict: { code, message }
+    });
+    if (records.some((record) => record.type !== desired.type && (record.type === "CNAME" || desired.type === "CNAME")))
+      return conflict("RECORD_CONFLICT", "CNAME cannot coexist with another record type");
+    const candidates = records.filter((record) => record.type === desired.type);
+    let existing;
+    if (desired.recordId) {
+      existing = candidates.find((record) => record.id === desired.recordId);
+      if (!existing)
+        throw new DnsError("RECORD_NOT_FOUND", "Explicit record ID does not match the requested name and type");
+    } else {
+      const owned = candidates.filter((record) => sameOwner(record.ownership, desired.owner));
+      if (owned.length > 1)
+        return conflict("AMBIGUOUS_RECORD", "Multiple owned records match; specify recordId");
+      existing = owned[0];
+      if (!existing && candidates.length) {
+        return candidates.some((record) => record.ownership) ? conflict("OWNERSHIP_MISMATCH", "Name is already used by a different owner") : conflict("RECORD_CONFLICT", "Existing records have no matching owner; automatic adoption is disabled");
+      }
+    }
+    if (existing && !sameOwner(existing.ownership, desired.owner))
+      return conflict(existing.ownership ? "OWNERSHIP_MISMATCH" : "RECORD_CONFLICT", "Selected record does not belong to this owner");
+    desired = adapter.normalizeDesired?.(desired, existing) ?? desired;
+    if (existing && !matches(existing, desired) && !adapter.capabilities.update)
+      throw new DnsError("CAPABILITY_UNSUPPORTED", "Adapter does not support updates");
+    checkAborted(context);
+    return { ...base, desired, existing, operation: existing ? matches(existing, desired) ? "noop" : "update" : "create" };
+  }
+  function ref(record, owner) {
+    return {
+      provider: adapter.id,
+      zoneId: record.zoneId,
+      recordId: record.id,
+      owner,
+      snapshot: { name: record.name, type: record.type, content: record.content }
+    };
+  }
+  async function ensure(input, context) {
+    const desired = normalize(input);
+    return locked("write", async () => {
+      const first = await plan(desired, context);
+      if (first.conflict)
+        throw new DnsError(first.conflict.code, first.conflict.message);
+      const current = await plan(desired, context);
+      if (fingerprint(first) !== fingerprint(current))
+        throw new DnsError("PLAN_STALE", "Records changed during planning; run ensure again");
+      checkAborted(context);
+      const effective = current.desired;
+      let actual = current.existing;
+      if (current.operation !== "noop") {
+        try {
+          actual = current.operation === "create" ? await adapter.createRecord(current.zone.id, effective, context) : await adapter.updateRecord(current.zone.id, current.existing.id, effective, context);
+        } catch (error) {
+          if (!(error instanceof DnsError) || !error.retriable || context?.signal?.aborted)
+            throw error;
+          const recovered = await plan(desired, context);
+          if (recovered.operation !== "noop" || !recovered.existing)
+            throw error;
+          actual = recovered.existing;
+        }
+        actual = await adapter.getRecord(current.zone.id, actual.id, context);
+      }
+      if (!actual || !matches(actual, effective))
+        throw new DnsError("PLAN_STALE", "Provider state does not match the requested record after the operation");
+      const action = current.operation === "create" ? "created" : current.operation === "update" ? "updated" : "unchanged";
+      context?.logger?.({ event: `record:${action}`, requestId: context.requestId, recordId: actual.id });
+      return { action, record: actual, ref: ref(actual, desired.owner) };
+    });
+  }
+  async function remove(target, context) {
+    if (target.provider !== adapter.id || !target.zoneId || !target.recordId || !target.owner?.application || !target.owner.id)
+      throw new DnsError("CONFIG_INVALID", "A complete record ref for this provider is required");
+    return locked("write", async () => {
+      checkAborted(context);
+      const record = await adapter.getRecord(target.zoneId, target.recordId, context);
+      if (!record)
+        return { action: "already-absent" };
+      if (!sameOwner(record.ownership, target.owner))
+        throw new DnsError("OWNERSHIP_MISMATCH", "Record owner changed; deletion refused");
+      if (target.snapshot && fingerprint(target.snapshot) !== fingerprint({ name: record.name, type: record.type, content: record.content }))
+        throw new DnsError("PLAN_STALE", "Record changed since selection; deletion refused");
+      checkAborted(context);
+      await adapter.deleteRecord(target.zoneId, target.recordId, context);
+      if (await adapter.getRecord(target.zoneId, target.recordId, context))
+        throw new DnsError("PLAN_STALE", "Provider still returns the deleted record");
+      context?.logger?.({ event: "record:removed", requestId: context.requestId, recordId: target.recordId });
+      return { action: "removed" };
+    });
+  }
+  return { plan, ensure, remove };
+}
+
+export { assertInZone, createDnsManager, desiredFromConfig, findConfigFile, loadDnsConfig, normalizeContent, normalizeHostname, normalizeProjectName, renderHostname, resolveDnsConfig, validateConfig, validateLabel };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@flash-dns/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.0",
+  "description": "DNS naming, configuration and ownership-aware reconciliation.",
+  "license": "MIT",
+  "homepage": "https://github.com/flash-tunnel/flash-dns#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flash-tunnel/flash-dns.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/flash-tunnel/flash-dns/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@flash-dns/config": "0.1.0",
+    "@flash-dns/types": "0.1.0",
+    "jiti": "2.6.1",
+    "unconfig": "7.5.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "stub": "unbuild --stub",
+    "typecheck": "tsc --noEmit"
+  }
 }