@serve.zone/dcrouter-apiclient 33.0.1 → 34.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,78 @@
1
+ import type { TDnsRecordType } from './dns-record.js';
2
+ /**
3
+ * Who changed DNS state.
4
+ *
5
+ * - 'operator' → a person through the ops API.
6
+ * - 'automation' → a dcrouter reconciler, named by its `managedBy` namespace.
7
+ * - 'provider' → a change dcrouter observed at a DNS provider while mirroring its zone.
8
+ */
9
+ export type TDnsMutationActorKind = 'operator' | 'automation' | 'provider';
10
+ /**
11
+ * What a journal entry records.
12
+ *
13
+ * Record mutations: 'create', 'update', 'delete'. Ownership changes that leave the record's
14
+ * DNS data alone: 'release' (an owned record loses its owner and becomes an operator record),
15
+ * 'handoff' (an owned record moves to another owner of the same namespace). Provider
16
+ * observations: 'mirror-update' and 'mirror-delete' (the local mirror follows a change made at
17
+ * the provider). Migration to a provider: 'link' (a local record is linked to the provider record
18
+ * the migration created for it), 'adopt' (a local record is linked to the identical record the
19
+ * target zone already held) and 'migrate' (the zone switches to the provider). Protected-hostname
20
+ * list changes: 'protect', 'unprotect'.
21
+ */
22
+ export type TDnsMutationOperation = 'create' | 'update' | 'delete' | 'adopt' | 'release' | 'handoff' | 'mirror-update' | 'mirror-delete' | 'link' | 'migrate' | 'protect' | 'unprotect';
23
+ /**
24
+ * - 'pending' → the intent was written and the mutation has not reported back. A pending entry
25
+ * that never completes marks a mutation interrupted between its provider call and its local
26
+ * write (for a provider observation: between the entry and the mirror write).
27
+ * - 'applied' → the mutation took effect.
28
+ * - 'failed' → the mutation ran and failed; nothing it reports as failed took effect. For a
29
+ * provider observation: the mirror did not follow because the record changed in between.
30
+ * - 'refused' → the mutation never ran (protected hostname, or a record the actor does not own).
31
+ * - 'observed' → a provider-side change the local mirror followed while mirroring the zone.
32
+ */
33
+ export type TDnsMutationOutcome = 'pending' | 'applied' | 'failed' | 'refused' | 'observed';
34
+ /** The DNS data and ownership of one record before or after a mutation. */
35
+ export interface IDnsMutationRecordState {
36
+ name: string;
37
+ type: TDnsRecordType;
38
+ value: string;
39
+ ttl: number;
40
+ proxied?: boolean;
41
+ managedBy?: string;
42
+ managedOwnerId?: string;
43
+ managedRecordKey?: string;
44
+ providerRecordId?: string;
45
+ }
46
+ /** One durable DNS mutation journal entry. Entries are kept for 180 days. */
47
+ export interface IDnsMutationJournalEntry {
48
+ id: string;
49
+ /** When the intent (or the refusal or observation) was written, Unix epoch milliseconds. */
50
+ createdAt: number;
51
+ /** When the outcome was written; absent while `outcome` is 'pending'. */
52
+ completedAt?: number;
53
+ operation: TDnsMutationOperation;
54
+ outcome: TDnsMutationOutcome;
55
+ actorKind: TDnsMutationActorKind;
56
+ /** Operator user id, automation namespace (`managedBy`) or provider id. */
57
+ actor: string;
58
+ /** What started the mutation, e.g. 'ops-api', 'gateway-route-sync', 'orphan-prune', 'provider-sync'. */
59
+ trigger: string;
60
+ /** Why, in words. */
61
+ reason: string;
62
+ /** Owner within the actor's namespace on whose behalf the mutation ran. */
63
+ ownerId?: string;
64
+ domainId?: string;
65
+ zoneName?: string;
66
+ /** Canonical hostname (lowercase, no trailing dot) the entry concerns. */
67
+ hostname: string;
68
+ recordId?: string;
69
+ before?: IDnsMutationRecordState;
70
+ after?: IDnsMutationRecordState;
71
+ /** Failure or refusal detail. */
72
+ message?: string;
73
+ }
74
+ /** Stable seek position for descending journal pages. */
75
+ export interface IDnsMutationJournalCursor {
76
+ createdAt: number;
77
+ id: string;
78
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLW11dGF0aW9uLWpvdXJuYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvZG5zLW11dGF0aW9uLWpvdXJuYWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
@@ -0,0 +1,16 @@
1
+ /**
2
+ * A hostname no dcrouter automation may change.
3
+ *
4
+ * Every dcrouter automation that writes DNS records (route DNS, the gateway-client hostname
5
+ * manager, the mail DNS reconciler, migration to a DNS provider) is refused every create, update, delete, adoption and owner
6
+ * handoff of any record type at this exact name; it may only release its ownership of a record
7
+ * there, which leaves the record in place as an operator record. Operator changes through the
8
+ * ops API are not bound. Provider zone mirroring still records what the provider holds.
9
+ */
10
+ export interface IDnsProtectedHostname {
11
+ /** Exact hostname: lowercase, no trailing dot, no wildcard. Subdomains are not covered. */
12
+ hostname: string;
13
+ reason: string;
14
+ createdBy: string;
15
+ createdAt: number;
16
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLXByb3RlY3RlZC1ob3N0bmFtZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvZGF0YS9kbnMtcHJvdGVjdGVkLWhvc3RuYW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==
@@ -45,4 +45,9 @@ export interface IDnsRecord {
45
45
  managedOwnerId?: string;
46
46
  /** Deterministic record identity. Unique only when present. */
47
47
  managedRecordKey?: string;
48
+ /**
49
+ * True when the record's name is on the protected-hostname list (see
50
+ * `IDnsProtectedHostname`): no automation may change it. Absent otherwise.
51
+ */
52
+ protectedHostname?: true;
48
53
  }
@@ -9,6 +9,8 @@ export * from './domain.js';
9
9
  export * from './dns-authority.js';
10
10
  export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
+ export * from './dns-mutation-journal.js';
13
+ export * from './dns-protected-hostname.js';
12
14
  export * from './acme-config.js';
13
15
  export * from './email-domain.js';
14
16
  export * from './email-settings.js';
@@ -9,6 +9,8 @@ export * from './domain.js';
9
9
  export * from './dns-authority.js';
10
10
  export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
+ export * from './dns-mutation-journal.js';
13
+ export * from './dns-protected-hostname.js';
12
14
  export * from './acme-config.js';
13
15
  export * from './email-domain.js';
14
16
  export * from './email-settings.js';
@@ -16,4 +18,4 @@ export * from './smtp-account.js';
16
18
  export * from './security-policy.js';
17
19
  export * from './config-events.js';
18
20
  export * from './testing.js';
19
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQyJ9
21
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL2RhdGEvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUMifQ==
@@ -0,0 +1,28 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IDnsMutationJournalCursor, IDnsMutationJournalEntry } from '../data/dns-mutation-journal.js';
4
+ /**
5
+ * Read the DNS mutation journal, newest first. Every filter is optional and they combine.
6
+ */
7
+ export interface IReq_GetDnsMutationJournal extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetDnsMutationJournal> {
8
+ method: 'getDnsMutationJournal';
9
+ request: {
10
+ identity?: authInterfaces.IIdentity;
11
+ apiToken?: string;
12
+ /** Exact hostname; compared lowercase without a trailing dot. */
13
+ hostname?: string;
14
+ /** Zone name, e.g. 'example.com'. */
15
+ zoneName?: string;
16
+ /** Entries written at or after this time, Unix epoch milliseconds. */
17
+ since?: number;
18
+ /** Entries written at or before this time, Unix epoch milliseconds. */
19
+ until?: number;
20
+ /** Page size, 1 to 200; 100 when omitted. */
21
+ limit?: number;
22
+ cursor?: IDnsMutationJournalCursor;
23
+ };
24
+ response: {
25
+ entries: IDnsMutationJournalEntry[];
26
+ nextCursor?: IDnsMutationJournalCursor;
27
+ };
28
+ }
@@ -0,0 +1,2 @@
1
+ import * as plugins from '../plugins.js';
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLW11dGF0aW9uLWpvdXJuYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2Rucy1tdXRhdGlvbi1qb3VybmFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=
@@ -0,0 +1,50 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IDnsProtectedHostname } from '../data/dns-protected-hostname.js';
4
+ /**
5
+ * List the hostnames no automation may change. Requires an admin identity or an admin API token.
6
+ */
7
+ export interface IReq_GetDnsProtectedHostnames extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetDnsProtectedHostnames> {
8
+ method: 'getDnsProtectedHostnames';
9
+ request: {
10
+ identity?: authInterfaces.IIdentity;
11
+ apiToken?: string;
12
+ };
13
+ response: {
14
+ hostnames: IDnsProtectedHostname[];
15
+ };
16
+ }
17
+ /**
18
+ * Protect one exact hostname. Requires an admin identity or an admin API token. The hostname is
19
+ * stored lowercase without a trailing dot; a wildcard is refused. Adding a hostname that is
20
+ * already protected changes nothing and answers success.
21
+ */
22
+ export interface IReq_AddDnsProtectedHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_AddDnsProtectedHostname> {
23
+ method: 'addDnsProtectedHostname';
24
+ request: {
25
+ identity?: authInterfaces.IIdentity;
26
+ apiToken?: string;
27
+ hostname: string;
28
+ reason: string;
29
+ };
30
+ response: {
31
+ success: boolean;
32
+ hostname?: IDnsProtectedHostname;
33
+ message?: string;
34
+ };
35
+ }
36
+ /**
37
+ * Remove one hostname from the protected list. Requires an admin identity or an admin API token.
38
+ */
39
+ export interface IReq_RemoveDnsProtectedHostname extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RemoveDnsProtectedHostname> {
40
+ method: 'removeDnsProtectedHostname';
41
+ request: {
42
+ identity?: authInterfaces.IIdentity;
43
+ apiToken?: string;
44
+ hostname: string;
45
+ };
46
+ response: {
47
+ success: boolean;
48
+ message?: string;
49
+ };
50
+ }
@@ -0,0 +1,2 @@
1
+ import * as plugins from '../plugins.js';
2
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLXByb3RlY3RlZC1ob3N0bmFtZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2Rucy1wcm90ZWN0ZWQtaG9zdG5hbWVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sZUFBZSxDQUFDIn0=
@@ -119,6 +119,12 @@ export interface IReq_SyncDomain extends plugins.typedrequestInterfaces.implemen
119
119
  /**
120
120
  * Migrate a domain between dcrouter-hosted and provider-managed (or between providers).
121
121
  * Records are transferred to the target and the domain source/providerId are updated.
122
+ *
123
+ * A migration to a provider reads the target zone first and refuses, with
124
+ * nothing written, when a record there conflicts with a migrated record;
125
+ * identical target records are adopted. A failed create rolls back exactly the
126
+ * records the run created. Records at the target that the migration did not
127
+ * create are never changed or deleted.
122
128
  */
123
129
  export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_MigrateDomain> {
124
130
  method: 'migrateDomain';
@@ -130,7 +136,10 @@ export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.imple
130
136
  targetSource: import('../data/domain.js').TDomainSource;
131
137
  /** Required when targetSource is 'provider'. */
132
138
  targetProviderId?: string;
133
- /** When migrating to a provider: delete all existing records at the provider first. */
139
+ /**
140
+ * @deprecated Refused when `true`: a migration never deletes records at the
141
+ * provider that it did not create. Omit it or send `false`.
142
+ */
134
143
  deleteExistingProviderRecords?: boolean;
135
144
  };
136
145
  response: {
@@ -18,6 +18,8 @@ export * from './dns-providers.js';
18
18
  export * from './domains.js';
19
19
  export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
+ export * from './dns-protected-hostnames.js';
22
+ export * from './dns-mutation-journal.js';
21
23
  export * from './acme-config.js';
22
24
  export * from './email-domains.js';
23
25
  export * from './email-settings.js';
@@ -18,6 +18,8 @@ export * from './dns-providers.js';
18
18
  export * from './domains.js';
19
19
  export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
+ export * from './dns-protected-hostnames.js';
22
+ export * from './dns-mutation-journal.js';
21
23
  export * from './acme-config.js';
22
24
  export * from './email-domains.js';
23
25
  export * from './email-settings.js';
@@ -27,4 +29,4 @@ export * from './workhoster.js';
27
29
  export * from './security-policy.js';
28
30
  export * from './config-events.js';
29
31
  export * from './testing.js';
30
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUMifQ==
32
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19pbnRlcmZhY2VzL3JlcXVlc3RzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDIn0=
package/package.json CHANGED
@@ -28,7 +28,7 @@
28
28
  "MAC authentication"
29
29
  ],
30
30
  "name": "@serve.zone/dcrouter-apiclient",
31
- "version": "33.0.1",
31
+ "version": "34.0.0",
32
32
  "type": "module",
33
33
  "description": "Object-oriented TypeScript client and shared TypedRequest contracts for the dcrouter OpsServer API.",
34
34
  "main": "./dist_ts_apiclient/index.js",
@@ -51,7 +51,7 @@
51
51
  "@push.rocks/smartmta": "^13.0.1",
52
52
  "@push.rocks/smartnetwork": "^4.10.1",
53
53
  "@push.rocks/smartproxy": "^27.22.0",
54
- "@serve.zone/interfaces": "^32.21.0"
54
+ "@serve.zone/interfaces": "^32.61.0"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=22.12.0"
@@ -0,0 +1,96 @@
1
+ import type { TDnsRecordType } from './dns-record.js';
2
+
3
+ /**
4
+ * Who changed DNS state.
5
+ *
6
+ * - 'operator' → a person through the ops API.
7
+ * - 'automation' → a dcrouter reconciler, named by its `managedBy` namespace.
8
+ * - 'provider' → a change dcrouter observed at a DNS provider while mirroring its zone.
9
+ */
10
+ export type TDnsMutationActorKind = 'operator' | 'automation' | 'provider';
11
+
12
+ /**
13
+ * What a journal entry records.
14
+ *
15
+ * Record mutations: 'create', 'update', 'delete'. Ownership changes that leave the record's
16
+ * DNS data alone: 'release' (an owned record loses its owner and becomes an operator record),
17
+ * 'handoff' (an owned record moves to another owner of the same namespace). Provider
18
+ * observations: 'mirror-update' and 'mirror-delete' (the local mirror follows a change made at
19
+ * the provider). Migration to a provider: 'link' (a local record is linked to the provider record
20
+ * the migration created for it), 'adopt' (a local record is linked to the identical record the
21
+ * target zone already held) and 'migrate' (the zone switches to the provider). Protected-hostname
22
+ * list changes: 'protect', 'unprotect'.
23
+ */
24
+ export type TDnsMutationOperation =
25
+ | 'create'
26
+ | 'update'
27
+ | 'delete'
28
+ | 'adopt'
29
+ | 'release'
30
+ | 'handoff'
31
+ | 'mirror-update'
32
+ | 'mirror-delete'
33
+ | 'link'
34
+ | 'migrate'
35
+ | 'protect'
36
+ | 'unprotect';
37
+
38
+ /**
39
+ * - 'pending' → the intent was written and the mutation has not reported back. A pending entry
40
+ * that never completes marks a mutation interrupted between its provider call and its local
41
+ * write (for a provider observation: between the entry and the mirror write).
42
+ * - 'applied' → the mutation took effect.
43
+ * - 'failed' → the mutation ran and failed; nothing it reports as failed took effect. For a
44
+ * provider observation: the mirror did not follow because the record changed in between.
45
+ * - 'refused' → the mutation never ran (protected hostname, or a record the actor does not own).
46
+ * - 'observed' → a provider-side change the local mirror followed while mirroring the zone.
47
+ */
48
+ export type TDnsMutationOutcome = 'pending' | 'applied' | 'failed' | 'refused' | 'observed';
49
+
50
+ /** The DNS data and ownership of one record before or after a mutation. */
51
+ export interface IDnsMutationRecordState {
52
+ name: string;
53
+ type: TDnsRecordType;
54
+ value: string;
55
+ ttl: number;
56
+ proxied?: boolean;
57
+ managedBy?: string;
58
+ managedOwnerId?: string;
59
+ managedRecordKey?: string;
60
+ providerRecordId?: string;
61
+ }
62
+
63
+ /** One durable DNS mutation journal entry. Entries are kept for 180 days. */
64
+ export interface IDnsMutationJournalEntry {
65
+ id: string;
66
+ /** When the intent (or the refusal or observation) was written, Unix epoch milliseconds. */
67
+ createdAt: number;
68
+ /** When the outcome was written; absent while `outcome` is 'pending'. */
69
+ completedAt?: number;
70
+ operation: TDnsMutationOperation;
71
+ outcome: TDnsMutationOutcome;
72
+ actorKind: TDnsMutationActorKind;
73
+ /** Operator user id, automation namespace (`managedBy`) or provider id. */
74
+ actor: string;
75
+ /** What started the mutation, e.g. 'ops-api', 'gateway-route-sync', 'orphan-prune', 'provider-sync'. */
76
+ trigger: string;
77
+ /** Why, in words. */
78
+ reason: string;
79
+ /** Owner within the actor's namespace on whose behalf the mutation ran. */
80
+ ownerId?: string;
81
+ domainId?: string;
82
+ zoneName?: string;
83
+ /** Canonical hostname (lowercase, no trailing dot) the entry concerns. */
84
+ hostname: string;
85
+ recordId?: string;
86
+ before?: IDnsMutationRecordState;
87
+ after?: IDnsMutationRecordState;
88
+ /** Failure or refusal detail. */
89
+ message?: string;
90
+ }
91
+
92
+ /** Stable seek position for descending journal pages. */
93
+ export interface IDnsMutationJournalCursor {
94
+ createdAt: number;
95
+ id: string;
96
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * A hostname no dcrouter automation may change.
3
+ *
4
+ * Every dcrouter automation that writes DNS records (route DNS, the gateway-client hostname
5
+ * manager, the mail DNS reconciler, migration to a DNS provider) is refused every create, update, delete, adoption and owner
6
+ * handoff of any record type at this exact name; it may only release its ownership of a record
7
+ * there, which leaves the record in place as an operator record. Operator changes through the
8
+ * ops API are not bound. Provider zone mirroring still records what the provider holds.
9
+ */
10
+ export interface IDnsProtectedHostname {
11
+ /** Exact hostname: lowercase, no trailing dot, no wildcard. Subdomains are not covered. */
12
+ hostname: string;
13
+ reason: string;
14
+ createdBy: string;
15
+ createdAt: number;
16
+ }
@@ -47,4 +47,9 @@ export interface IDnsRecord {
47
47
  managedOwnerId?: string;
48
48
  /** Deterministic record identity. Unique only when present. */
49
49
  managedRecordKey?: string;
50
+ /**
51
+ * True when the record's name is on the protected-hostname list (see
52
+ * `IDnsProtectedHostname`): no automation may change it. Absent otherwise.
53
+ */
54
+ protectedHostname?: true;
50
55
  }
@@ -9,6 +9,8 @@ export * from './domain.js';
9
9
  export * from './dns-authority.js';
10
10
  export * from './workhoster.js';
11
11
  export * from './dns-record.js';
12
+ export * from './dns-mutation-journal.js';
13
+ export * from './dns-protected-hostname.js';
12
14
  export * from './acme-config.js';
13
15
  export * from './email-domain.js';
14
16
  export * from './email-settings.js';
@@ -0,0 +1,35 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type {
4
+ IDnsMutationJournalCursor,
5
+ IDnsMutationJournalEntry,
6
+ } from '../data/dns-mutation-journal.js';
7
+
8
+ /**
9
+ * Read the DNS mutation journal, newest first. Every filter is optional and they combine.
10
+ */
11
+ export interface IReq_GetDnsMutationJournal extends plugins.typedrequestInterfaces.implementsTR<
12
+ plugins.typedrequestInterfaces.ITypedRequest,
13
+ IReq_GetDnsMutationJournal
14
+ > {
15
+ method: 'getDnsMutationJournal';
16
+ request: {
17
+ identity?: authInterfaces.IIdentity;
18
+ apiToken?: string;
19
+ /** Exact hostname; compared lowercase without a trailing dot. */
20
+ hostname?: string;
21
+ /** Zone name, e.g. 'example.com'. */
22
+ zoneName?: string;
23
+ /** Entries written at or after this time, Unix epoch milliseconds. */
24
+ since?: number;
25
+ /** Entries written at or before this time, Unix epoch milliseconds. */
26
+ until?: number;
27
+ /** Page size, 1 to 200; 100 when omitted. */
28
+ limit?: number;
29
+ cursor?: IDnsMutationJournalCursor;
30
+ };
31
+ response: {
32
+ entries: IDnsMutationJournalEntry[];
33
+ nextCursor?: IDnsMutationJournalCursor;
34
+ };
35
+ }
@@ -0,0 +1,66 @@
1
+ import * as plugins from '../plugins.js';
2
+ import type * as authInterfaces from '../data/auth.js';
3
+ import type { IDnsProtectedHostname } from '../data/dns-protected-hostname.js';
4
+
5
+ // ============================================================================
6
+ // Protected DNS hostnames (admin)
7
+ // ============================================================================
8
+
9
+ /**
10
+ * List the hostnames no automation may change. Requires an admin identity or an admin API token.
11
+ */
12
+ export interface IReq_GetDnsProtectedHostnames extends plugins.typedrequestInterfaces.implementsTR<
13
+ plugins.typedrequestInterfaces.ITypedRequest,
14
+ IReq_GetDnsProtectedHostnames
15
+ > {
16
+ method: 'getDnsProtectedHostnames';
17
+ request: {
18
+ identity?: authInterfaces.IIdentity;
19
+ apiToken?: string;
20
+ };
21
+ response: {
22
+ hostnames: IDnsProtectedHostname[];
23
+ };
24
+ }
25
+
26
+ /**
27
+ * Protect one exact hostname. Requires an admin identity or an admin API token. The hostname is
28
+ * stored lowercase without a trailing dot; a wildcard is refused. Adding a hostname that is
29
+ * already protected changes nothing and answers success.
30
+ */
31
+ export interface IReq_AddDnsProtectedHostname extends plugins.typedrequestInterfaces.implementsTR<
32
+ plugins.typedrequestInterfaces.ITypedRequest,
33
+ IReq_AddDnsProtectedHostname
34
+ > {
35
+ method: 'addDnsProtectedHostname';
36
+ request: {
37
+ identity?: authInterfaces.IIdentity;
38
+ apiToken?: string;
39
+ hostname: string;
40
+ reason: string;
41
+ };
42
+ response: {
43
+ success: boolean;
44
+ hostname?: IDnsProtectedHostname;
45
+ message?: string;
46
+ };
47
+ }
48
+
49
+ /**
50
+ * Remove one hostname from the protected list. Requires an admin identity or an admin API token.
51
+ */
52
+ export interface IReq_RemoveDnsProtectedHostname extends plugins.typedrequestInterfaces.implementsTR<
53
+ plugins.typedrequestInterfaces.ITypedRequest,
54
+ IReq_RemoveDnsProtectedHostname
55
+ > {
56
+ method: 'removeDnsProtectedHostname';
57
+ request: {
58
+ identity?: authInterfaces.IIdentity;
59
+ apiToken?: string;
60
+ hostname: string;
61
+ };
62
+ response: {
63
+ success: boolean;
64
+ message?: string;
65
+ };
66
+ }
@@ -152,6 +152,12 @@ export interface IReq_SyncDomain extends plugins.typedrequestInterfaces.implemen
152
152
  /**
153
153
  * Migrate a domain between dcrouter-hosted and provider-managed (or between providers).
154
154
  * Records are transferred to the target and the domain source/providerId are updated.
155
+ *
156
+ * A migration to a provider reads the target zone first and refuses, with
157
+ * nothing written, when a record there conflicts with a migrated record;
158
+ * identical target records are adopted. A failed create rolls back exactly the
159
+ * records the run created. Records at the target that the migration did not
160
+ * create are never changed or deleted.
155
161
  */
156
162
  export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.implementsTR<
157
163
  plugins.typedrequestInterfaces.ITypedRequest,
@@ -166,7 +172,10 @@ export interface IReq_MigrateDomain extends plugins.typedrequestInterfaces.imple
166
172
  targetSource: import('../data/domain.js').TDomainSource;
167
173
  /** Required when targetSource is 'provider'. */
168
174
  targetProviderId?: string;
169
- /** When migrating to a provider: delete all existing records at the provider first. */
175
+ /**
176
+ * @deprecated Refused when `true`: a migration never deletes records at the
177
+ * provider that it did not create. Omit it or send `false`.
178
+ */
170
179
  deleteExistingProviderRecords?: boolean;
171
180
  };
172
181
  response: {
@@ -18,6 +18,8 @@ export * from './dns-providers.js';
18
18
  export * from './domains.js';
19
19
  export * from './dns-authority.js';
20
20
  export * from './dns-records.js';
21
+ export * from './dns-protected-hostnames.js';
22
+ export * from './dns-mutation-journal.js';
21
23
  export * from './acme-config.js';
22
24
  export * from './email-domains.js';
23
25
  export * from './email-settings.js';