@aglyn/tenant-data-admin 1.0.0-beta.271 → 1.0.0-beta.273

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aglyn/tenant-data-admin",
3
- "version": "1.0.0-beta.271",
3
+ "version": "1.0.0-beta.273",
4
4
  "license": "Apache-2.0",
5
5
  "homepage": "https://aglyn.com",
6
6
  "repository": {
@@ -25,12 +25,12 @@
25
25
  "./package.json": "./package.json"
26
26
  },
27
27
  "dependencies": {
28
- "@aglyn/aglyn": "1.0.0-beta.271",
29
- "@aglyn/shared-util-email": "1.0.0-beta.271",
30
- "@aglyn/shared-util-fbserver": "1.0.0-beta.271",
31
- "@aglyn/shared-util-first-touch": "1.0.0-beta.271",
32
- "@aglyn/shared-util-http": "1.0.0-beta.271",
33
- "@aglyn/shared-util-tools": "1.0.0-beta.271",
28
+ "@aglyn/aglyn": "1.0.0-beta.273",
29
+ "@aglyn/shared-util-email": "1.0.0-beta.273",
30
+ "@aglyn/shared-util-fbserver": "1.0.0-beta.273",
31
+ "@aglyn/shared-util-first-touch": "1.0.0-beta.273",
32
+ "@aglyn/shared-util-http": "1.0.0-beta.273",
33
+ "@aglyn/shared-util-tools": "1.0.0-beta.273",
34
34
  "@msgpack/msgpack": "^3.1.3",
35
35
  "@swc/helpers": "0.5.23",
36
36
  "sharp": "^0.35.5",
@@ -0,0 +1,205 @@
1
+ /**
2
+ * @license
3
+ * Copyright 2026 Aglyn LLC
4
+ *
5
+ * Licensed under the Apache License, Version 2.0 (the "License");
6
+ * you may not use this file except in compliance with the License.
7
+ * You may obtain a copy of the License at
8
+ *
9
+ * http://www.apache.org/licenses/LICENSE-2.0
10
+ *
11
+ * Unless required by applicable law or agreed to in writing, software
12
+ * distributed under the License is distributed on an "AS IS" BASIS,
13
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ * See the License for the specific language governing permissions and
15
+ * limitations under the License.
16
+ */
17
+ import { type DnsLookupResult } from './dns-probe';
18
+ /** The subcollection under `orgs/{orgId}`; the document id is the domain. */
19
+ export declare const DOMAIN_OWNERSHIP_CLAIMS_COLLECTION = "domainOwnershipClaims";
20
+ /** The `name` of the home page meta tag that carries the token. */
21
+ export declare const DOMAIN_OWNERSHIP_META_NAME = "aglyn-site-verification";
22
+ /** The system email that carries the one-time code. */
23
+ export declare const DOMAIN_OWNERSHIP_CODE_EMAIL_KEY = "domain-ownership-code";
24
+ /** How long an emailed code works. */
25
+ export declare const DOMAIN_OWNERSHIP_CODE_TTL_MS: number;
26
+ /** Wrong codes allowed before the code is burned and a new one must be sent. */
27
+ export declare const DOMAIN_OWNERSHIP_CODE_MAX_ATTEMPTS = 5;
28
+ /** The least time between two codes for one claim. */
29
+ export declare const DOMAIN_OWNERSHIP_CODE_RESEND_MS: number;
30
+ /** Codes one workspace may send in an hour, across every claim. */
31
+ export declare const DOMAIN_OWNERSHIP_CODES_PER_ORG_PER_HOUR = 10;
32
+ /** Codes one address may receive in an hour, from every workspace. */
33
+ export declare const DOMAIN_OWNERSHIP_CODES_PER_ADDRESS_PER_HOUR = 5;
34
+ /**
35
+ * How long a proof stands before an import asks for it again. A domain can
36
+ * lapse and be bought by someone else; a month is short enough that the new
37
+ * owner's content is not imported on the old owner's proof.
38
+ */
39
+ export declare const DOMAIN_OWNERSHIP_PROOF_MAX_AGE_MS: number;
40
+ export type DomainOwnershipMethod = 'dns' | 'meta' | 'email';
41
+ /** What one check found. `unreachable` is evidence in neither direction. */
42
+ export type DomainOwnershipCheckStatus = 'proven' | 'not-yet' | 'unreachable';
43
+ /** The stored document. Times are epoch milliseconds. */
44
+ export interface DomainOwnershipClaimDoc {
45
+ domain: string;
46
+ token: string;
47
+ status: 'pending' | 'proven';
48
+ createdAt: number;
49
+ createdBy: string;
50
+ provenMethod?: DomainOwnershipMethod;
51
+ provenAt?: number;
52
+ /** The record host, the page, or the address the proof came from. */
53
+ provenDetail?: string;
54
+ lastCheckedAt?: number;
55
+ lastChecks?: Partial<Record<DomainOwnershipMethod, DomainOwnershipCheckStatus>>;
56
+ emailCode?: {
57
+ address: string;
58
+ /** HMAC-SHA256 of the code, keyed by the signing secret. Never the code. */
59
+ hash: string;
60
+ sentAt: number;
61
+ expiresAt: number;
62
+ attempts: number;
63
+ } | null;
64
+ }
65
+ /** What the console is shown: the instructions, never the code's hash. */
66
+ export interface DomainOwnershipClaimView {
67
+ domain: string;
68
+ status: 'pending' | 'proven';
69
+ /** False once a proof is older than {@link DOMAIN_OWNERSHIP_PROOF_MAX_AGE_MS}. */
70
+ current: boolean;
71
+ provenMethod: DomainOwnershipMethod | null;
72
+ provenAt: number | null;
73
+ provenDetail: string | null;
74
+ lastChecks: Partial<Record<DomainOwnershipMethod, DomainOwnershipCheckStatus>>;
75
+ dns: {
76
+ host: string;
77
+ type: 'TXT';
78
+ value: string;
79
+ };
80
+ meta: {
81
+ name: string;
82
+ content: string;
83
+ tag: string;
84
+ };
85
+ email: {
86
+ /** Addresses must end in `@<domain>`. */
87
+ domain: string;
88
+ pendingAddress: string | null;
89
+ expiresAt: number | null;
90
+ attemptsLeft: number | null;
91
+ };
92
+ }
93
+ export interface DomainOwnershipCheckResult {
94
+ method: DomainOwnershipMethod;
95
+ status: DomainOwnershipCheckStatus;
96
+ /** A sentence for the person: what was looked at, and what to do next. */
97
+ message: string;
98
+ claim: DomainOwnershipClaimView;
99
+ }
100
+ /** `{ value, error }`, both keys always present, as `validateSsoDomain` does. */
101
+ export interface OwnershipDomainCheck {
102
+ domain: string | null;
103
+ error: string | null;
104
+ }
105
+ /** A home page's `aglyn-site-verification` values, read by the caller. */
106
+ export type ReadVerificationMeta = (domain: string) => Promise<{
107
+ answered: boolean;
108
+ values: string[];
109
+ url?: string;
110
+ }>;
111
+ /** Sends the code; the default is {@link deliverDomainOwnershipCode}. */
112
+ export type DeliverDomainOwnershipCode = (input: {
113
+ orgId: string;
114
+ org: Record<string, unknown> | null;
115
+ domain: string;
116
+ address: string;
117
+ code: string;
118
+ expiresInMinutes: number;
119
+ }) => Promise<{
120
+ sent: boolean;
121
+ status?: number;
122
+ error?: string;
123
+ }>;
124
+ export interface DomainOwnershipDeps {
125
+ firestore?: FirebaseFirestore.Firestore;
126
+ lookupTxt?: (host: string) => Promise<DnsLookupResult<string>>;
127
+ readVerificationMeta?: ReadVerificationMeta;
128
+ deliverCode?: DeliverDomainOwnershipCode;
129
+ now?: () => number;
130
+ /** The HMAC key for codes; the default is `TOKEN_SIGNING_SECRET`. */
131
+ secret?: () => string;
132
+ mintToken?: () => string;
133
+ mintCode?: () => string;
134
+ }
135
+ /**
136
+ * The domain a claim is about: lowercased, any scheme, path, port or address
137
+ * prefix a person pasted removed, and a leading `www.` folded into the bare
138
+ * name, because the site's two names are one site to its owner and the
139
+ * crawler treats them as one origin.
140
+ */
141
+ export declare function normalizeOwnershipDomain(input: string): OwnershipDomainCheck;
142
+ /** The TXT record host for a domain. */
143
+ export declare function domainOwnershipRecordHost(domain: string): string;
144
+ /** The meta tag a person pastes into their home page's `<head>`. */
145
+ export declare function domainOwnershipMetaTag(token: string): string;
146
+ /** Exact, whole-value match, for the reason `recordsProveOwnership` gives. */
147
+ export declare function metaValuesProveOwnership(values: readonly string[], token: string): boolean;
148
+ /**
149
+ * The address a code may go to: a plausible mailbox whose domain IS the
150
+ * claim's domain (the `www.` twin included), and nothing else. A parent or a
151
+ * sibling domain proves nothing about this one.
152
+ */
153
+ export declare function ownershipEmailAddress(input: string, domain: string): string | null;
154
+ /** HMAC of a code, bound to the claim and the address it was sent to. */
155
+ export declare function hashOwnershipCode(secret: string, input: {
156
+ orgId: string;
157
+ domain: string;
158
+ address: string;
159
+ code: string;
160
+ }): string;
161
+ /** Whether a stored proof is still one an import may rely on. */
162
+ export declare function isOwnershipProofCurrent(claim: Pick<DomainOwnershipClaimDoc, 'status' | 'provenAt'> | null | undefined, now: number): boolean;
163
+ export declare function domainOwnershipClaimView(claim: DomainOwnershipClaimDoc, now: number): DomainOwnershipClaimView;
164
+ /**
165
+ * Start (or re-read) a claim. Idempotent: an existing claim keeps its token,
166
+ * because a new one would break a record or tag the person already published.
167
+ */
168
+ export declare function issueDomainOwnershipClaim(orgId: string, rawDomain: string, uid: string, deps?: DomainOwnershipDeps): Promise<{
169
+ claim: DomainOwnershipClaimView | null;
170
+ error: string | null;
171
+ }>;
172
+ /** Every claim the org holds, newest first. */
173
+ export declare function listDomainOwnershipClaims(orgId: string, deps?: DomainOwnershipDeps): Promise<DomainOwnershipClaimView[]>;
174
+ /**
175
+ * Whether the org holds a CURRENT proof for the domain: the one question an
176
+ * import asks before it pulls a page or an image.
177
+ */
178
+ export declare function isDomainOwnershipProven(orgId: string, rawDomain: string, deps?: DomainOwnershipDeps): Promise<boolean>;
179
+ /** Look for the DNS record or the meta tag now. */
180
+ export declare function checkDomainOwnership(orgId: string, rawDomain: string, method: 'dns' | 'meta', deps?: DomainOwnershipDeps): Promise<{
181
+ result: DomainOwnershipCheckResult | null;
182
+ error: string | null;
183
+ }>;
184
+ /** Email a one-time code to an address at the domain. */
185
+ export declare function sendDomainOwnershipCode(orgId: string, rawDomain: string, rawAddress: string, context: {
186
+ org: Record<string, unknown> | null;
187
+ }, deps?: DomainOwnershipDeps): Promise<{
188
+ claim: DomainOwnershipClaimView | null;
189
+ error: string | null;
190
+ status: number;
191
+ }>;
192
+ /**
193
+ * Check a code the person typed. Counted in a transaction, so parallel
194
+ * guesses cannot get past the attempt limit between a read and a write.
195
+ */
196
+ export declare function confirmDomainOwnershipCode(orgId: string, rawDomain: string, rawCode: string, deps?: DomainOwnershipDeps): Promise<{
197
+ result: DomainOwnershipCheckResult | null;
198
+ error: string | null;
199
+ }>;
200
+ /**
201
+ * Sends the `domain-ownership-code` system email in the workspace's brand,
202
+ * after two ceilings: per workspace, so one cannot mail a domain's whole
203
+ * staff, and per address, so no address is flooded from many workspaces.
204
+ */
205
+ export declare const deliverDomainOwnershipCode: DeliverDomainOwnershipCode;