@kanorio/sdk 1.0.0 → 1.2.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.
- package/README.md +41 -2
- package/dist/customer-oauth.d.ts +21 -21
- package/dist/customer-oauth.js +12 -12
- package/dist/customer.d.ts +22 -22
- package/dist/customer.js +20 -11
- package/dist/delivery.d.ts +9 -9
- package/dist/delivery.js +6 -6
- package/dist/edge.d.ts +25 -21
- package/dist/edge.js +36 -20
- package/dist/forms.d.ts +33 -14
- package/dist/forms.js +20 -14
- package/dist/generated/delivery.d.ts +564 -13
- package/dist/generated/management.d.ts +790 -81
- package/dist/http.d.ts +13 -13
- package/dist/http.js +8 -8
- package/dist/image.d.ts +77 -0
- package/dist/image.js +78 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +4 -3
- package/dist/locales.d.ts +22 -22
- package/dist/locales.js +12 -12
- package/dist/management.d.ts +5 -5
- package/dist/management.js +3 -3
- package/dist/next.d.ts +66 -0
- package/dist/next.js +58 -0
- package/dist/paginate.d.ts +3 -3
- package/dist/paginate.js +3 -3
- package/dist/preview.d.ts +13 -13
- package/dist/preview.js +11 -11
- package/dist/protection.d.ts +18 -18
- package/dist/protection.js +11 -11
- package/dist/revalidate.d.ts +22 -22
- package/dist/revalidate.js +14 -14
- package/dist/seo.d.ts +137 -21
- package/dist/seo.js +113 -21
- package/dist/server-key.d.ts +2 -2
- package/dist/server-key.js +2 -2
- package/dist/shared/api/delivery/cache-tags.d.ts +41 -39
- package/dist/shared/api/delivery/cache-tags.js +36 -34
- package/dist/shared/api/server-key.d.ts +32 -28
- package/dist/shared/api/server-key.js +41 -33
- package/dist/shared/business-registry/attribution.d.ts +5 -5
- package/dist/shared/business-registry/attribution.js +4 -4
- package/dist/shared/business-registry/define.d.ts +1 -1
- package/dist/shared/business-registry/define.js +1 -1
- package/dist/shared/business-registry/formats/eu-vat.js +4 -4
- package/dist/shared/business-registry/formats/hk-br.d.ts +2 -2
- package/dist/shared/business-registry/formats/hk-br.js +4 -4
- package/dist/shared/business-registry/formats/jp-trn.d.ts +3 -3
- package/dist/shared/business-registry/formats/jp-trn.js +4 -4
- package/dist/shared/business-registry/formats/kr-brn.d.ts +2 -2
- package/dist/shared/business-registry/formats/kr-brn.js +3 -3
- package/dist/shared/business-registry/formats/my.d.ts +3 -3
- package/dist/shared/business-registry/formats/my.js +4 -4
- package/dist/shared/business-registry/formats/sg-uen.js +4 -4
- package/dist/shared/business-registry/formats/tw-vat.d.ts +5 -5
- package/dist/shared/business-registry/formats/tw-vat.js +6 -6
- package/dist/shared/business-registry/index.js +1 -1
- package/dist/shared/business-registry/lookup-wire.d.ts +9 -9
- package/dist/shared/business-registry/lookup-wire.js +4 -4
- package/dist/shared/business-registry/normalize.d.ts +3 -3
- package/dist/shared/business-registry/normalize.js +4 -4
- package/dist/shared/business-registry/registry.d.ts +9 -9
- package/dist/shared/business-registry/registry.js +13 -13
- package/dist/shared/business-registry/types.d.ts +20 -20
- package/dist/shared/business-registry/types.js +6 -6
- package/dist/shared/localization/locale-path.d.ts +18 -18
- package/dist/shared/localization/locale-path.js +18 -18
- package/dist/shared/localization/request-locale.d.ts +16 -16
- package/dist/shared/localization/request-locale.js +13 -13
- package/dist/shared/seo/alternates.d.ts +26 -26
- package/dist/shared/seo/alternates.js +18 -18
- package/dist/shared/types/forms-logic.d.ts +28 -28
- package/dist/shared/types/forms-logic.js +27 -27
- package/dist/shared/types/number-input.d.ts +2 -2
- package/dist/shared/types/number-input.js +3 -3
- package/dist/shared/utils/redirect-matching.d.ts +33 -24
- package/dist/shared/utils/redirect-matching.js +73 -40
- package/dist/typed.d.ts +5 -5
- package/dist/typed.js +3 -3
- package/package.json +15 -10
|
@@ -1,31 +1,31 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
/**
|
|
3
|
-
* Content Delivery API
|
|
3
|
+
* Cache tags of the Content Delivery API (the single source of truth).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* A response's tags say which content it used; an event's tags say which content changed. Both come from the functions in this file,
|
|
6
|
+
* and a contract matrix in Kanorio's tests checks every pairing: what should be cleared is cleared, and what should not is never touched.
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
* -
|
|
10
|
-
* -
|
|
11
|
-
* -
|
|
12
|
-
* -
|
|
13
|
-
* -
|
|
14
|
-
*
|
|
15
|
-
* -
|
|
8
|
+
* Layers (one response carries both broad and narrow tags, like CDN surrogate keys):
|
|
9
|
+
* - Site `site:{id}`: on every response; sent only by events for a full-site publish and for changes to the locale set (enabled, disabled, removed, prefix changed, primary changed)
|
|
10
|
+
* - Locale `locale:{code}`: on every response of a secondary locale; sent when a full-site translation finishes or translated site settings go live
|
|
11
|
+
* - Content `page:{id}`, `item:{id}`, `product:{id}`, `form:{id}`: on the response in every locale; sent when primary-locale content goes live (untranslated fields fall back to the primary locale, so every locale is cleared)
|
|
12
|
+
* - Content plus locale `page:{id}@en-US`: only on that locale's response; sent when that locale's translation goes live, leaving other locales alone
|
|
13
|
+
* - Lists `pages`, `collection:{key}`, `products` (plus locale): on list responses only, not per item (events send the list tags anyway, and Next.js allows at most 128 tags per cache entry);
|
|
14
|
+
* single-item responses do not carry list tags, so another item going live does not clear them. `collection:{key}:items` is every single-item response of the collection (all replaced when the field structure changes)
|
|
15
|
+
* - Derived `search`, `seo`, `redirects`: search, SEO files and the redirect table; sent along with content events that change them
|
|
16
16
|
*
|
|
17
|
-
*
|
|
18
|
-
* `revalidateTag`
|
|
19
|
-
*
|
|
17
|
+
* Tags use the locale code, not the URL prefix (owners can change the prefix); the locale is appended with `@`, apart from the colon of `type:id`.
|
|
18
|
+
* `revalidateTag` matches literally, with no wildcards, so events must list concrete tags. Pure functions with no server-only dependency, shared by Kanorio's server, its edge worker and the SDK
|
|
19
|
+
* (the SDK's copy is made by `pnpm --filter @kanorio/sdk gen`, and a contract test keeps the two identical).
|
|
20
20
|
*/
|
|
21
21
|
export const DELIVERY_CACHE_TAGS_HEADER = "x-kanorio-cache-tags";
|
|
22
|
-
/**
|
|
22
|
+
/** Maximum tags per response: Next.js caps a cache entry at 128, leaving room for the external front end's own tags */
|
|
23
23
|
export const DELIVERY_CACHE_TAG_LIMIT = 100;
|
|
24
|
-
/**
|
|
24
|
+
/** Separator between a tag and its locale: `item:abc@en-US` */
|
|
25
25
|
export const CACHE_TAG_LOCALE_SEPARATOR = "@";
|
|
26
|
-
/** SDK
|
|
26
|
+
/** Namespace the SDK adds when handing tags to a framework (Next.js `revalidateTag`, `next.tags`), to avoid clashing with the site's own tags such as `pages` or `seo` */
|
|
27
27
|
export const DEFAULT_CACHE_TAG_PREFIX = "kanorio:";
|
|
28
|
-
/**
|
|
28
|
+
/** The tag vocabulary; strings are only assembled here */
|
|
29
29
|
export const cacheTag = {
|
|
30
30
|
site: (siteId) => `site:${siteId}`,
|
|
31
31
|
locale: (locale) => `locale:${locale}`,
|
|
@@ -36,7 +36,7 @@ export const cacheTag = {
|
|
|
36
36
|
footer: () => "footer",
|
|
37
37
|
collections: () => "collections",
|
|
38
38
|
collection: (key) => `collection:${key}`,
|
|
39
|
-
/**
|
|
39
|
+
/** Every single-item response of the collection: used when the field structure changes or a batch exceeds the limit */
|
|
40
40
|
collectionItems: (key) => `collection:${key}:items`,
|
|
41
41
|
item: (itemId) => `item:${itemId}`,
|
|
42
42
|
products: () => "products",
|
|
@@ -71,8 +71,8 @@ function unique(tags) {
|
|
|
71
71
|
return out;
|
|
72
72
|
}
|
|
73
73
|
/**
|
|
74
|
-
*
|
|
75
|
-
*
|
|
74
|
+
* The locale dimension of a response: the primary locale (`locale` is null) is left as is; a secondary locale gets the locale appended to every content and list tag (not to `site:`), plus `locale:{code}`.
|
|
75
|
+
* The edge calls this with the request's normalized locale code (omitted and explicitly primary are both null); the server only declares content dependencies.
|
|
76
76
|
*/
|
|
77
77
|
export function localizeCacheTags(tags, locale) {
|
|
78
78
|
const base = unique(tags);
|
|
@@ -85,7 +85,7 @@ const NARROW_PREFIXES = ["item:", "page:", "product:"];
|
|
|
85
85
|
function isNarrowCacheTag(tag) {
|
|
86
86
|
return NARROW_PREFIXES.some((prefix) => tag.startsWith(prefix));
|
|
87
87
|
}
|
|
88
|
-
/**
|
|
88
|
+
/** Over the limit, single-content tags are dropped first (list tags stay, since events send them anyway); if still over, only the first `limit` are kept */
|
|
89
89
|
export function capCacheTags(tags, limit = DELIVERY_CACHE_TAG_LIMIT) {
|
|
90
90
|
const all = unique(tags);
|
|
91
91
|
if (all.length <= limit)
|
|
@@ -93,7 +93,7 @@ export function capCacheTags(tags, limit = DELIVERY_CACHE_TAG_LIMIT) {
|
|
|
93
93
|
const wide = all.filter((tag) => !isNarrowCacheTag(tag));
|
|
94
94
|
return wide.length <= limit ? wide : wide.slice(0, limit);
|
|
95
95
|
}
|
|
96
|
-
/** `X-Kanorio-Cache-Tags`
|
|
96
|
+
/** `X-Kanorio-Cache-Tags` is space-separated */
|
|
97
97
|
export function parseCacheTagsHeader(raw) {
|
|
98
98
|
if (!raw)
|
|
99
99
|
return [];
|
|
@@ -102,7 +102,7 @@ export function parseCacheTagsHeader(raw) {
|
|
|
102
102
|
export function formatCacheTagsHeader(tags) {
|
|
103
103
|
return unique(tags).join(" ");
|
|
104
104
|
}
|
|
105
|
-
/**
|
|
105
|
+
/** Adds the namespace before handing tags to a framework; an empty `prefix` leaves them as is */
|
|
106
106
|
export function prefixCacheTags(tags, prefix = DEFAULT_CACHE_TAG_PREFIX) {
|
|
107
107
|
return unique(tags).map((tag) => `${prefix}${tag}`);
|
|
108
108
|
}
|
|
@@ -137,7 +137,7 @@ export const responseCacheTags = {
|
|
|
137
137
|
redirects: (siteId) => [cacheTag.site(siteId), cacheTag.redirects()],
|
|
138
138
|
reviews: (siteId, productId) => [cacheTag.site(siteId), cacheTag.reviews(), ...(productId ? [cacheTag.product(productId)] : [])],
|
|
139
139
|
};
|
|
140
|
-
/**
|
|
140
|
+
/** System collections: when an article-like record's translation changes, the collection item has changed */
|
|
141
141
|
const SYSTEM_COLLECTION_OF_ENTITY = {
|
|
142
142
|
post: "blog",
|
|
143
143
|
post_category: "blog_categories",
|
|
@@ -145,12 +145,12 @@ const SYSTEM_COLLECTION_OF_ENTITY = {
|
|
|
145
145
|
author: "authors",
|
|
146
146
|
};
|
|
147
147
|
export const eventCacheTags = {
|
|
148
|
-
/**
|
|
148
|
+
/** Full-site publish: pages, header and footer, redirects and SEO files may all change */
|
|
149
149
|
sitePublished: (siteId) => [cacheTag.site(siteId), cacheTag.pages(), cacheTag.globals(), cacheTag.redirects(), cacheTag.seo()],
|
|
150
|
-
/**
|
|
150
|
+
/** A single page going live, updated, taken offline or deleted: `site:` is not sent, so other pages stay; a changed URL also sends `redirects` */
|
|
151
151
|
pageChanged: (input) => [cacheTag.pages(), cacheTag.page(input.pageId), cacheTag.seo(), cacheTag.search(), ...(input.renamed ? [cacheTag.redirects()] : [])],
|
|
152
152
|
itemChanged: (input) => [cacheTag.collection(input.collectionKey), cacheTag.item(input.itemId), cacheTag.seo(), cacheTag.search()],
|
|
153
|
-
/**
|
|
153
|
+
/** Bulk: items are listed one by one when their tags fit; otherwise every single-item response of the collection is cleared (list tags are always sent) */
|
|
154
154
|
itemsBulkChanged: (input) => {
|
|
155
155
|
const wide = [cacheTag.collection(input.collectionKey), cacheTag.seo(), cacheTag.search()];
|
|
156
156
|
const narrow = input.itemIds.map((id) => cacheTag.item(id));
|
|
@@ -158,15 +158,17 @@ export const eventCacheTags = {
|
|
|
158
158
|
return [...wide, ...narrow];
|
|
159
159
|
return [...wide, cacheTag.collectionItems(input.collectionKey)];
|
|
160
160
|
},
|
|
161
|
-
/**
|
|
161
|
+
/** The field structure changed: the collection list, the item list and every single-item response of the collection (projected fields changed) */
|
|
162
162
|
schemaChanged: (input) => [cacheTag.collections(), cacheTag.collection(input.collectionKey), cacheTag.collectionItems(input.collectionKey)],
|
|
163
|
-
/**
|
|
163
|
+
/** A form's definition changed, it was paused or resumed, or it moved to or from the trash: the form's own response in every locale */
|
|
164
|
+
formChanged: (formId) => [cacheTag.form(formId)],
|
|
165
|
+
/** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
|
|
164
166
|
localeChanged: (siteId) => [cacheTag.site(siteId)],
|
|
165
|
-
/**
|
|
167
|
+
/** A full-site translation finished: every response in that locale */
|
|
166
168
|
translationJobCompleted: (locale) => [cacheTag.locale(locale)],
|
|
167
169
|
/**
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
+
* One record's translation in one locale went live or was deleted: only locale-specific tags are sent, so the caches of other locales and the primary locale stay.
|
|
171
|
+
* Site settings and site announcements frame the whole locale, hence `locale:{code}`; product options, categories and course outlines have no single product id, hence `products@{code}`.
|
|
170
172
|
*/
|
|
171
173
|
translationChanged: (input) => {
|
|
172
174
|
const l = (tag) => localizeCacheTag(tag, input.locale);
|
|
@@ -1,43 +1,47 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
|
|
5
|
+
* (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
|
|
6
|
+
* See the Authentication page of the developer documentation.
|
|
7
7
|
*/
|
|
8
|
-
/**
|
|
8
|
+
/** The header the server sends the key in */
|
|
9
9
|
export declare const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
|
|
10
|
-
/**
|
|
10
|
+
/** The visitor IP relayed by the server; trusted only when the key has been verified */
|
|
11
11
|
export declare const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
12
12
|
/**
|
|
13
|
-
*
|
|
14
|
-
*
|
|
13
|
+
* Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
|
|
14
|
+
* `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
|
|
15
15
|
*/
|
|
16
16
|
export declare const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
|
|
17
17
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
18
|
+
* Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
|
|
19
|
+
* no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
|
|
20
20
|
*/
|
|
21
21
|
export declare const STOREFRONT_SERVER_SCOPE = "storefront:server";
|
|
22
|
-
|
|
22
|
+
/**
|
|
23
|
+
* The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
|
|
24
|
+
* that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
|
|
25
|
+
*/
|
|
26
|
+
export declare const SERVER_KEY_PREFIX = "knr_sk_";
|
|
23
27
|
export declare function isServerKeyFormat(raw: string): boolean;
|
|
24
28
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
29
|
+
* A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
|
|
30
|
+
* The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
|
|
27
31
|
*/
|
|
28
32
|
export declare const PROBE_FAKE_SERVER_KEY: string;
|
|
29
|
-
/**
|
|
33
|
+
/** A service account's purpose: decided by whether its grant carries `STOREFRONT_SERVER_SCOPE`, and fixed after creation */
|
|
30
34
|
export type ServiceAccountPurpose = "management" | "storefront_server";
|
|
31
35
|
export declare function purposeOfGrant(permissions: readonly string[]): ServiceAccountPurpose;
|
|
32
|
-
/**
|
|
36
|
+
/** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
|
|
33
37
|
export declare const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
|
|
34
|
-
/**
|
|
38
|
+
/** Response of the edge worker's verification call to the server */
|
|
35
39
|
export interface ServerKeyVerifyResponse {
|
|
36
40
|
valid: boolean;
|
|
37
41
|
tokenId?: string;
|
|
38
|
-
/** ISO
|
|
42
|
+
/** ISO time; null means it does not expire */
|
|
39
43
|
expiresAt?: string | null;
|
|
40
|
-
/**
|
|
44
|
+
/** Source restrictions (an empty array means none); matched against the actual connecting IP and ASN */
|
|
41
45
|
allowedCidrs?: string[];
|
|
42
46
|
allowedAsns?: number[];
|
|
43
47
|
}
|
|
@@ -45,26 +49,26 @@ export interface ParsedIp {
|
|
|
45
49
|
version: 4 | 6;
|
|
46
50
|
bytes: number[];
|
|
47
51
|
}
|
|
48
|
-
/**
|
|
52
|
+
/** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
|
|
49
53
|
export declare function parseIp(raw: string): ParsedIp | null;
|
|
50
54
|
export declare function isPublicIp(ip: ParsedIp): boolean;
|
|
51
55
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
56
|
+
* The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
|
|
57
|
+
* A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
|
|
54
58
|
*/
|
|
55
59
|
export declare function normalizeVisitorIp(raw: string | null | undefined): string | null;
|
|
56
|
-
/**
|
|
60
|
+
/** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
|
|
57
61
|
export declare function rateLimitKeyForIp(ip: string): string;
|
|
58
62
|
export interface ParsedCidr {
|
|
59
63
|
version: 4 | 6;
|
|
60
64
|
bytes: number[];
|
|
61
65
|
bits: number;
|
|
62
|
-
/**
|
|
66
|
+
/** Normalized form (network address and prefix length) */
|
|
63
67
|
text: string;
|
|
64
68
|
}
|
|
65
69
|
/**
|
|
66
|
-
*
|
|
67
|
-
*
|
|
70
|
+
* Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
|
|
71
|
+
* Rejected: malformed input, non-public ranges and prefixes that are too wide.
|
|
68
72
|
*/
|
|
69
73
|
export declare function parseAllowedCidr(raw: string): ParsedCidr | null;
|
|
70
74
|
export declare function ipInCidr(ip: string, cidr: ParsedCidr): boolean;
|
|
@@ -76,9 +80,9 @@ export interface SourcePolicy {
|
|
|
76
80
|
}
|
|
77
81
|
export declare function hasSourcePolicy(policy: SourcePolicy): boolean;
|
|
78
82
|
/**
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
83
|
+
* Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
|
|
84
|
+
* Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
|
|
85
|
+
* With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
|
|
82
86
|
*/
|
|
83
87
|
export declare function isSourceAllowed(policy: SourcePolicy, source: {
|
|
84
88
|
ip: string | null;
|
|
@@ -1,42 +1,50 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
3
|
+
* The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
|
|
6
|
+
* (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
|
|
7
|
+
* See the Authentication page of the developer documentation.
|
|
8
8
|
*/
|
|
9
|
-
/**
|
|
9
|
+
/** The header the server sends the key in */
|
|
10
10
|
export const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
|
|
11
|
-
/**
|
|
11
|
+
/** The visitor IP relayed by the server; trusted only when the key has been verified */
|
|
12
12
|
export const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
13
13
|
/**
|
|
14
|
-
*
|
|
15
|
-
*
|
|
14
|
+
* Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
|
|
15
|
+
* `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
|
|
16
16
|
*/
|
|
17
17
|
export const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
|
|
18
18
|
/**
|
|
19
|
-
*
|
|
20
|
-
*
|
|
19
|
+
* Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
|
|
20
|
+
* no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
|
|
21
21
|
*/
|
|
22
22
|
export const STOREFRONT_SERVER_SCOPE = "storefront:server";
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
/**
|
|
24
|
+
* The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
|
|
25
|
+
* that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
|
|
26
|
+
*/
|
|
27
|
+
export const SERVER_KEY_PREFIX = "knr_sk_";
|
|
28
|
+
/**
|
|
29
|
+
* The prefix followed by 43 base64url characters (32 bytes). A malformed key is rejected without a lookup.
|
|
30
|
+
* Server keys have this one prefix only.
|
|
31
|
+
* Keys issued earlier with `knr_sa_` are not accepted and must be created again.
|
|
32
|
+
*/
|
|
33
|
+
const SERVER_KEY_PATTERN = /^knr_sk_[A-Za-z0-9_-]{43}$/;
|
|
26
34
|
export function isServerKeyFormat(raw) {
|
|
27
35
|
return SERVER_KEY_PATTERN.test(raw);
|
|
28
36
|
}
|
|
29
37
|
/**
|
|
30
|
-
*
|
|
31
|
-
*
|
|
38
|
+
* A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
|
|
39
|
+
* The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
|
|
32
40
|
*/
|
|
33
41
|
export const PROBE_FAKE_SERVER_KEY = `${SERVER_KEY_PREFIX}${"0".repeat(43)}`;
|
|
34
42
|
export function purposeOfGrant(permissions) {
|
|
35
43
|
return permissions.includes(STOREFRONT_SERVER_SCOPE) ? "storefront_server" : "management";
|
|
36
44
|
}
|
|
37
|
-
/**
|
|
45
|
+
/** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
|
|
38
46
|
export const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
|
|
39
|
-
//
|
|
47
|
+
// --- IP utilities (shared by the edge worker and the server; no node:net dependency, so they run on Workers) ---
|
|
40
48
|
function parseIpv4(value) {
|
|
41
49
|
const parts = value.split(".");
|
|
42
50
|
if (parts.length !== 4)
|
|
@@ -52,7 +60,7 @@ function parseIpv4(value) {
|
|
|
52
60
|
}
|
|
53
61
|
return out;
|
|
54
62
|
}
|
|
55
|
-
/** IPv6
|
|
63
|
+
/** IPv6 to 16 bytes; supports `::` compression and a trailing IPv4 (`::ffff:1.2.3.4`). Zone ids are not accepted */
|
|
56
64
|
function parseIpv6(value) {
|
|
57
65
|
if (!value.includes(":") || value.includes("%"))
|
|
58
66
|
return null;
|
|
@@ -94,7 +102,7 @@ function parseIpv6(value) {
|
|
|
94
102
|
bytes.splice(12, 4, ...tailV4);
|
|
95
103
|
return bytes;
|
|
96
104
|
}
|
|
97
|
-
/**
|
|
105
|
+
/** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
|
|
98
106
|
export function parseIp(raw) {
|
|
99
107
|
const value = raw.trim();
|
|
100
108
|
if (!value || value.length > 45)
|
|
@@ -121,7 +129,7 @@ function inPrefix(bytes, prefix, bits) {
|
|
|
121
129
|
const mask = (0xff << (8 - rest)) & 0xff;
|
|
122
130
|
return ((bytes[full] ?? 0) & mask) === ((prefix[full] ?? 0) & mask);
|
|
123
131
|
}
|
|
124
|
-
/**
|
|
132
|
+
/** Addresses not routable on the public internet: private, loopback, link-local, CGNAT, documentation, multicast and reserved ranges */
|
|
125
133
|
const NON_PUBLIC_V4 = [
|
|
126
134
|
[[0, 0, 0, 0], 8],
|
|
127
135
|
[[10, 0, 0, 0], 8],
|
|
@@ -138,15 +146,15 @@ const NON_PUBLIC_V4 = [
|
|
|
138
146
|
[[224, 0, 0, 0], 3],
|
|
139
147
|
];
|
|
140
148
|
const NON_PUBLIC_V6 = [
|
|
141
|
-
// ::/127
|
|
149
|
+
// ::/127 (unspecified and loopback)
|
|
142
150
|
[[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 127],
|
|
143
151
|
// fc00::/7 unique local
|
|
144
152
|
[[0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 7],
|
|
145
153
|
// fe80::/10 link-local
|
|
146
154
|
[[0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 10],
|
|
147
|
-
// ff00::/8
|
|
155
|
+
// ff00::/8 multicast
|
|
148
156
|
[[0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 8],
|
|
149
|
-
// 2001:db8::/32
|
|
157
|
+
// 2001:db8::/32 documentation
|
|
150
158
|
[[0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 32],
|
|
151
159
|
];
|
|
152
160
|
export function isPublicIp(ip) {
|
|
@@ -162,8 +170,8 @@ function formatIp(ip) {
|
|
|
162
170
|
return groups.join(":");
|
|
163
171
|
}
|
|
164
172
|
/**
|
|
165
|
-
*
|
|
166
|
-
*
|
|
173
|
+
* The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
|
|
174
|
+
* A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
|
|
167
175
|
*/
|
|
168
176
|
export function normalizeVisitorIp(raw) {
|
|
169
177
|
if (!raw)
|
|
@@ -173,7 +181,7 @@ export function normalizeVisitorIp(raw) {
|
|
|
173
181
|
return null;
|
|
174
182
|
return formatIp(parsed);
|
|
175
183
|
}
|
|
176
|
-
/**
|
|
184
|
+
/** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
|
|
177
185
|
export function rateLimitKeyForIp(ip) {
|
|
178
186
|
const parsed = parseIp(ip);
|
|
179
187
|
if (!parsed)
|
|
@@ -182,11 +190,11 @@ export function rateLimitKeyForIp(ip) {
|
|
|
182
190
|
return formatIp(parsed);
|
|
183
191
|
return `${formatIp({ version: 6, bytes: [...parsed.bytes.slice(0, 8), 0, 0, 0, 0, 0, 0, 0, 0] })}/64`;
|
|
184
192
|
}
|
|
185
|
-
/**
|
|
193
|
+
/** The widest ranges accepted are IPv4 /8 and IPv6 /16: anything wider is no restriction at all */
|
|
186
194
|
const MIN_PREFIX_BITS = { 4: 8, 6: 16 };
|
|
187
195
|
/**
|
|
188
|
-
*
|
|
189
|
-
*
|
|
196
|
+
* Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
|
|
197
|
+
* Rejected: malformed input, non-public ranges and prefixes that are too wide.
|
|
190
198
|
*/
|
|
191
199
|
export function parseAllowedCidr(raw) {
|
|
192
200
|
const value = raw.trim();
|
|
@@ -228,9 +236,9 @@ export function hasSourcePolicy(policy) {
|
|
|
228
236
|
return policy.allowedCidrs.length > 0 || policy.allowedAsns.length > 0;
|
|
229
237
|
}
|
|
230
238
|
/**
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
239
|
+
* Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
|
|
240
|
+
* Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
|
|
241
|
+
* With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
|
|
234
242
|
*/
|
|
235
243
|
export function isSourceAllowed(policy, source) {
|
|
236
244
|
if (policy.allowedCidrs.length > 0) {
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
import type { RegistryAttributionWire } from "./types.js";
|
|
2
|
-
/**
|
|
2
|
+
/** The source of registry data (which registry it is, not the route it was fetched through) */
|
|
3
3
|
export type RegistrySource = "fia_tax_registration" | "gcis_company";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
|
|
6
|
+
* so responses, prefilled screens and documentation all carry this.
|
|
7
7
|
*/
|
|
8
8
|
export declare const REGISTRY_ATTRIBUTION: Record<RegistrySource, RegistryAttributionWire>;
|
|
9
9
|
export declare function registryAttribution(source: RegistrySource, dataDate?: string): RegistryAttributionWire;
|
|
10
10
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
11
|
+
* Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
|
|
12
|
+
* Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
|
|
13
13
|
*/
|
|
14
14
|
export declare function registryProviderName(attribution: Pick<RegistryAttributionWire, "provider" | "providerEn">, locale: string | null | undefined): string;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
|
|
3
|
+
* so responses, prefilled screens and documentation all carry this.
|
|
4
4
|
*/
|
|
5
5
|
export const REGISTRY_ATTRIBUTION = {
|
|
6
6
|
fia_tax_registration: {
|
|
@@ -20,8 +20,8 @@ export function registryAttribution(source, dataDate) {
|
|
|
20
20
|
return dataDate ? { ...REGISTRY_ATTRIBUTION[source], dataDate } : REGISTRY_ATTRIBUTION[source];
|
|
21
21
|
}
|
|
22
22
|
/**
|
|
23
|
-
*
|
|
24
|
-
*
|
|
23
|
+
* Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
|
|
24
|
+
* Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
|
|
25
25
|
*/
|
|
26
26
|
export function registryProviderName(attribution, locale) {
|
|
27
27
|
return locale?.toLowerCase().startsWith("zh") ? attribution.provider : attribution.providerEn;
|
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import type { TaxIdFormatDefinition } from "./types.js";
|
|
2
|
-
/**
|
|
2
|
+
/** Declares a tax ID format. It only narrows types; formats are registered in registry.ts */
|
|
3
3
|
export declare function defineTaxIdFormat(definition: TaxIdFormatDefinition): TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* EU VAT identification number: a member state prefix plus that country's format. Greece's prefix is EL (its country code is GR).
|
|
6
|
+
* The country formats follow the EU's public VIES notes and are not verified against each country's official documentation yet, so this only warns and never blocks;
|
|
7
|
+
* the countries' check digits are not implemented either. When the user types only the number, the prefix is added.
|
|
8
8
|
*/
|
|
9
9
|
const EU_VAT = {
|
|
10
10
|
AT: { prefix: "AT", pattern: /^ATU\d{8}$/, example: "ATU12345678" },
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
|
|
3
|
+
* The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
|
|
4
4
|
*/
|
|
5
5
|
export declare const hkBr: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
|
|
6
|
+
* The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
|
|
7
7
|
*/
|
|
8
8
|
export const hkBr = defineTaxIdFormat({
|
|
9
9
|
type: "hk_br",
|
|
@@ -11,7 +11,7 @@ export const hkBr = defineTaxIdFormat({
|
|
|
11
11
|
stripeType: "hk_br",
|
|
12
12
|
normalize: (cleaned) => {
|
|
13
13
|
const digits = stripSeparators(cleaned);
|
|
14
|
-
//
|
|
14
|
+
// The full certificate number: 8 digits, a 3-digit branch, year and month and so on, 16 digits in total
|
|
15
15
|
return /^\d{16}$/.test(digits) && /\D/.test(cleaned) ? digits.slice(0, 8) : digits;
|
|
16
16
|
},
|
|
17
17
|
validate: (normalized) => (/^\d{8}$/.test(normalized) ? null : "FORMAT"),
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
|
|
3
|
+
* A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
|
|
4
|
+
* so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
|
|
5
5
|
*/
|
|
6
6
|
export declare const jpTrn: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
|
|
6
|
+
* A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
|
|
7
|
+
* so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
|
|
8
8
|
*/
|
|
9
9
|
export const jpTrn = defineTaxIdFormat({
|
|
10
10
|
type: "jp_trn",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
|
|
3
|
+
* The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
|
|
4
4
|
*/
|
|
5
5
|
export declare function isValidKrBrn(normalized: string): boolean;
|
|
6
6
|
export declare const krBrn: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
const WEIGHTS = [1, 3, 7, 1, 3, 7, 1, 3, 5];
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
6
|
+
* South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
|
|
7
|
+
* The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
|
|
8
8
|
*/
|
|
9
9
|
export function isValidKrBrn(normalized) {
|
|
10
10
|
if (!/^\d{10}$/.test(normalized))
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* - my_itn
|
|
4
|
-
* - my_sst
|
|
2
|
+
* Malaysian tax IDs. Both follow public examples and are not verified against the official documentation of LHDN and Customs yet, so they only warn and never block.
|
|
3
|
+
* - my_itn: income tax number (TIN), a 1 to 2 letter category plus digits (for example C 1234567890); this is the one e-invoicing (MyInvois) uses
|
|
4
|
+
* - my_sst: Sales and Service Tax registration number (for example A12-3456-78912345)
|
|
5
5
|
*/
|
|
6
6
|
export declare const myItn: import("../types.js").TaxIdFormatDefinition;
|
|
7
7
|
export declare const mySst: import("../types.js").TaxIdFormatDefinition;
|