main
ply4 git calls56 ms45 KiB3 cachedprotocol v2
294 lines14 KiBRaw
1// /v1 remote policy. decideRemote is the discriminated result. The fetch layer takes only an
2// AllowedRemote and re-runs the same policy on every request; it never follows a redirect. ply follows the first
3// GET info/refs (git's http.followRedirects=initial) and vets the new base with remoteAllowUrl, the same policy.
4import { fail, plyError } from 'ply';
5import { atIndex, captureGroup, chainGet, recordGet } from './absent.ts';
6import { unwrapOr } from './option.ts';
7import { extractRequestPath, rawPathHasUnsafeSegment } from './pathguard.ts';
9const allowedRemoteBrand: unique symbol = Symbol('AllowedRemote');
11export type AllowedRemote = {
12 readonly [allowedRemoteBrand]: 'AllowedRemote';
13 readonly href: string;
14 readonly origin: string;
15 readonly hostname: string;
16 readonly host: string;
17};
19export type Rejected = { readonly kind: 'rejected'; readonly reason: RemoteReason };
20export type Allowed = { readonly kind: 'allowed'; readonly remote: AllowedRemote };
21export type RemoteDecision = Allowed | Rejected;
23export type RemoteReason =
24 | 'empty'
25 | 'too_long'
26 | 'not_url'
27 | 'userinfo'
28 | 'query'
29 | 'fragment'
30 | 'trailing_dot'
31 | 'scheme'
32 | 'port'
33 | 'ip_literal'
34 | 'wildcard_dns'
35 | 'private_name'
36 | 'single_label'
37 | 'bad_path'
38 | 'control';
40const MAX_REMOTE = 2048;
42/** Wildcard-DNS names that answer with an address encoded in the label (or with 127.0.0.1 for the whole zone). */
43const WILDCARD_DNS = Object.freeze([
44 'nip.io',
45 'sslip.io',
46 'xip.io',
47 'localtest.me',
48 'lvh.me',
49 'vcap.me',
50 'lacolhost.com',
51 'localho.st',
52 'traefik.me',
53]);
55const PRIVATE_SUFFIX = /(^|\.)(localhost|local|localdomain|internal|intranet|lan|home\.arpa|corp|private)$/i;
57const REASON_TEXT: Record<RemoteReason, string> = {
58 empty: 'remote is required',
59 too_long: 'remote too long',
60 not_url: 'remote is not a URL',
61 userinfo: 'remote must not carry credentials; use Git-Authorization or Git-Token',
62 query: 'remote must not have a query or fragment',
63 fragment: 'remote must not have a query or fragment',
64 trailing_dot: 'remote host is not a public name',
65 scheme: 'remote must be https',
66 port: 'remote must use the default port',
67 ip_literal: 'remote must be a host name, not an IP address',
68 wildcard_dns: 'remote host is not a public name',
69 private_name: 'remote host is not a public name',
70 single_label: 'remote host is not a public name',
71 bad_path: 'remote is not a URL',
72 control: 'remote is not a URL',
73};
75export type FetchLike = typeof globalThis.fetch;
77function rejected(reason: RemoteReason): Rejected {
78 return { kind: 'rejected', reason };
81function brand(href: string, origin: string, hostname: string, host: string): AllowedRemote {
82 return { [allowedRemoteBrand]: 'AllowedRemote', href, origin, hostname, host };
85export function isAllowedRemote(value: unknown): value is AllowedRemote {
86 return !!value && typeof value === 'object' && (value as AllowedRemote)[allowedRemoteBrand] === 'AllowedRemote';
89/** True when the raw authority's host ends in `.`, even if a URL parser would keep or drop that dot. */
90export function authorityHasTrailingDot(raw: string): boolean {
91 const match = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(raw.trim());
92 const found = captureGroup(match, 1);
93 if (found.tag === 'none' || !found.value) return false;
94 let authority = found.value;
95 const at = authority.lastIndexOf('@');
96 if (at >= 0) authority = authority.slice(at + 1);
97 if (authority.startsWith('[')) {
98 const end = authority.indexOf(']');
99 return end >= 0 && authority.slice(end + 1).startsWith('.');
100 }
101 const colon = authority.lastIndexOf(':');
102 if (colon >= 0 && /^\d+$/.test(authority.slice(colon + 1))) authority = authority.slice(0, colon);
103 return authority.endsWith('.');
106function rawAuthorityHost(raw: string): string {
107 const match = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i.exec(raw.trim());
108 const found = captureGroup(match, 1);
109 if (found.tag === 'none' || !found.value) return '';
110 let authority = found.value;
111 const at = authority.lastIndexOf('@');
112 if (at >= 0) authority = authority.slice(at + 1);
113 if (authority.startsWith('[')) {
114 const end = authority.indexOf(']');
115 return end >= 0 ? authority.slice(1, end) : authority;
116 }
117 const colon = authority.lastIndexOf(':');
118 if (colon >= 0 && /^\d+$/.test(authority.slice(colon + 1))) return authority.slice(0, colon);
119 return authority;
122/** Decimal, octal, hex, dotted-quad, and IPv6 textual forms, before the URL parser rewrites them. */
123export function rawHostIsIpEncoding(host: string): boolean {
124 const bare = host.trim().replace(/^\[|\]$/g, '');
125 if (!bare) return false;
126 if (bare.includes(':')) return true;
127 if (/^0x[0-9a-f]+$/i.test(bare)) return true;
128 if (/^\d+$/.test(bare)) return true;
129 if (/^(\d+|0x[0-9a-f]+)(\.(\d+|0x[0-9a-f]+)){1,3}$/i.test(bare)) return true;
130 return false;
133export function isIpHostname(hostname: string): boolean {
134 if (hostname.startsWith('[') || hostname.includes(':')) return true;
135 if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) return true;
136 // 127.0.0.1.nip.io and 10.0.0.1.example.com both encode an address in the name.
137 return /(^|\.)(\d{1,3}\.){3}\d{1,3}(\.|$)/.test(hostname);
140export function isWildcardDns(hostname: string): boolean {
141 const host = hostname.toLowerCase().replace(/\.$/, '');
142 for (const suffix of WILDCARD_DNS) {
143 if (host === suffix || host.endsWith(`.${suffix}`)) return true;
144 }
145 return false;
148export function isPrivateName(hostname: string): boolean {
149 return PRIVATE_SUFFIX.test(hostname.toLowerCase().replace(/\.$/, ''));
152function requestUrl(input: RequestInfo | URL): string {
153 if (typeof input === 'string') return input;
154 if (input instanceof URL) return input.href;
155 return input.url;
158export type DecideOpts = Partial<{ allowQuery: boolean; maxLength: number }>;
160/**
161 * Strict parse of a caller-supplied remote. `allow` is an origin list (tests, ALLOW_REMOTE_ORIGINS)
162 * that may use http, an IP, and a non-default port. Everything else must be https on the default
163 * port, with a public DNS name: no IP literal in any encoding, no wildcard-DNS suffix, no trailing dot.
164 */
165export function decideRemote(raw: string, allow: readonly string[] = [], opts: DecideOpts = {}): RemoteDecision {
166 const maxField = chainGet(opts, 'maxLength');
167 const maxLength = maxField.tag === 'none' ? MAX_REMOTE : maxField.value as number;
168 if (typeof raw !== 'string' || !raw.trim()) return rejected('empty');
169 if (raw.length > maxLength) return rejected('too_long');
170 // oxlint-disable-next-line no-control-regex -- a remote with controls is not a URL
171 if (/[\u0000-\u001f\u007f\s]/.test(raw) || raw.includes('\\')) return rejected('control');
172 if (authorityHasTrailingDot(raw)) return rejected('trailing_dot');
173 const path = extractRequestPath(raw);
174 if (rawPathHasUnsafeSegment(path)) return rejected('bad_path');
175 const rawHost = rawAuthorityHost(raw);
176 let parsed: URL;
177 try { parsed = new URL(raw); }
178 catch { return rejected('not_url'); }
179 if (parsed.username || parsed.password) return rejected('userinfo');
180 if (parsed.hash) return rejected('fragment');
181 if (!opts.allowQuery && parsed.search) return rejected('query');
182 if (parsed.hostname.endsWith('.') || authorityHasTrailingDot(parsed.href)) return rejected('trailing_dot');
183 const hostname = parsed.hostname.toLowerCase();
184 const origin = parsed.origin;
185 // An allowlisted origin may be http, an IP, and a non-default port. The exemption is the
186 // canonical origin, so a decimal or hex spelling of that same host is still an IP literal
187 // unless the parsed origin itself is listed.
188 if (!allow.includes(origin)) {
189 if (parsed.protocol !== 'https:') return rejected('scheme');
190 if (parsed.port !== '') return rejected('port');
191 if (isIpHostname(hostname) || rawHostIsIpEncoding(rawHost) || rawHostIsIpEncoding(hostname)) return rejected('ip_literal');
192 if (isWildcardDns(hostname)) return rejected('wildcard_dns');
193 if (!hostname.includes('.')) return rejected('single_label');
194 if (isPrivateName(hostname)) return rejected('private_name');
195 }
196 const href = `${origin}${parsed.pathname}${opts.allowQuery ? parsed.search : ''}`;
197 return { kind: 'allowed', remote: brand(href, origin, hostname, parsed.host) };
200export function reasonText(reason: RemoteReason): string {
201 return REASON_TEXT[reason];
204/** Throw the /v1 bad_request the worker already returns. The value is an AllowedRemote. */
205export function checkRemote(raw: string, allow: readonly string[] = []): AllowedRemote {
206 const decision = decideRemote(raw, allow);
207 if (decision.kind === 'rejected') throw plyError('bad_request', reasonText(decision.reason));
208 return decision.remote;
211function authorizeHop(raw: string, home: AllowedRemote, allow: readonly string[]): AllowedRemote {
212 const decision = decideRemote(raw, allow, { allowQuery: true });
213 if (decision.kind === 'rejected') throw plyError('bad_request', reasonText(decision.reason));
214 if (decision.remote.origin !== home.origin) throw plyError('bad_request', REDIRECT_HOST);
215 return decision.remote;
218const REDIRECT_HOST = 'redirect host is not an allowlisted host';
220function rejectRedirectLocation(location: string): boolean {
221 if (!location || location.length > MAX_REMOTE) return true;
222 // oxlint-disable-next-line no-control-regex -- a redirect with controls is not followed
223 if (/[\u0000-\u001f\u007f]/.test(location) || location.includes('\\') || /%(2e|2f|5c)/i.test(location)) return true;
224 const path = unwrapOr(atIndex(location.split(/[?#]/), 0), '');
225 return rawPathHasUnsafeSegment(path.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(location) ? extractRequestPath(location.startsWith('/') ? `https://reject.invalid${path}` : location) : path);
228type Vetted = { readonly ok: true; readonly value: URL } | ReturnType<typeof fail<'bad_request'>>;
230/**
231 * ply's `allowUrl` for a /v1 or mirror transport (followRedirects 'initial'). ply calls it with the remote before any
232 * request and with the Location of a 3xx on the first GET info/refs before it rebases there. The same policy as every
233 * request: decideRemote (query allowed, since a Location keeps `?service=`), the same path checks, and the remote's
234 * origin. A refusal is the /v1 400 bad_request the guard has always answered for a redirect elsewhere.
235 */
236export function remoteAllowUrl(remote: AllowedRemote, allow: readonly string[] = []): (url: URL) => Vetted {
237 if (!isAllowedRemote(remote)) throw plyError('bad_request', 'remote was not allowlisted');
238 return url => {
239 const decision = decideRemote(url.href, allow, { allowQuery: true });
240 if (decision.kind === 'rejected') return fail('bad_request', reasonText(decision.reason));
241 if (decision.remote.origin !== remote.origin) return fail('bad_request', REDIRECT_HOST);
242 return { ok: true, value: url };
243 };
246/** The redirect options every ply transport on a remote gets: git's `http.followRedirects=initial`, vetted by allowUrl. */
247export function redirectOptions(remote: AllowedRemote, allow: readonly string[] = []): { readonly followRedirects: 'initial'; readonly allowUrl: (url: URL) => Vetted } {
248 return { followRedirects: 'initial', allowUrl: remoteAllowUrl(remote, allow) };
251/**
252 * Fetch wrapper ply calls. `remote` is the branded result of decideRemote. Every request is parsed again and must stay
253 * on that remote's origin, so a credential ply attaches cannot leave it. A 3xx is never followed here: ply follows the
254 * first GET info/refs itself (followRedirects 'initial', git's rule) and reports any other. A 3xx whose Location is
255 * missing, unsafe, or on another origin is refused here, before ply sees it; any other 3xx is handed to ply as is.
256 */
257export function createGuardedFetch(inner: FetchLike, remote: AllowedRemote, allow: readonly string[] = []): FetchLike {
258 if (!isAllowedRemote(remote)) throw plyError('bad_request', 'remote was not allowlisted');
259 const guarded: FetchLike = async (input, init) => {
260 const current = authorizeHop(requestUrl(input), remote, allow);
261 const methodField = chainGet(init, 'method');
262 const method = methodField.tag === 'none' ? 'GET' : methodField.value as string;
263 const bodyField = chainGet(init, 'body');
264 const body = bodyField.tag === 'none' ? null : bodyField.value;
265 // A stream (ply's push past its held size, ply#172) is sent once, with duplex.
266 const streamed = body instanceof ReadableStream;
267 if (body !== null && !(body instanceof Uint8Array) && !streamed) throw plyError('bad_request', 'upstream body is not bytes or a stream');
268 const initRecord = init !== null && typeof init === 'object' ? init as Record<string, unknown> : null;
269 const headerField = recordGet(initRecord, 'headers');
270 const signalField = chainGet(init, 'signal');
271 // 'error' (ply's choice for a stream under undici, which would tee the body for 'manual') is kept; never 'follow'.
272 const redirectField = chainGet(init, 'redirect');
273 const requestInit: RequestInit = { method, redirect: redirectField.tag === 'some' && redirectField.value === 'error' ? 'error' : 'manual' };
274 if (headerField.tag === 'some') requestInit.headers = headerField.value as HeadersInit;
275 if (body !== null) requestInit.body = body as BodyInit;
276 // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duplex is in fetch's RequestInit (workerd and undici) but not in lib.dom's
277 if (streamed) (requestInit as RequestInit & { duplex: 'half' }).duplex = 'half';
278 if (signalField.tag === 'some') requestInit.signal = signalField.value as AbortSignal;
279 const res = await inner(current.href, requestInit);
280 if (res.status >= 300 && res.status < 400) {
281 const location = res.headers.get('location');
282 let target: string | null = null;
283 if (location && !rejectRedirectLocation(location)) {
284 try { target = authorizeHop(new URL(location, current.href).href, remote, allow).href; } catch { target = null; }
285 }
286 if (target === null) {
287 if (res.body) await res.body.cancel().catch(() => {});
288 throw plyError('bad_request', REDIRECT_HOST);
289 }
290 }
291 return res;
292 };
293 return guarded;
Diagnostics4 git calls · 56 ms
CallStatusSizeTime056 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200145 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=145
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=145
git.pkt.payload.max=76
git.ls_refs.count=2
git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020040 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=41349
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=526b305930b8ef382f2d7a1f9c0238730a585921
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=6
git.pkt.data=4
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=41349
git.pkt.payload.max=41254
git.sideband.band1.bytes=41253
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=61
git.pack.bytes=41253
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=ab60efef4b7243678c75de64a4386986ee885c1c
git.pack.full=61
Open pack map
fetch2004.5 KiB · hit51 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=51
git.response.bytes=4586
git.response.cache=HIT
git.response.duration_ms=51
git.fetch.wants=9d58c35560f58e92f064da0400edec97064ad284
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4586
git.pkt.payload.max=4565
git.sideband.band1.bytes=4564
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
Ref
refs/heads/main
Commit
526b305930b8ef382f2d7a1f9c0238730a585921
cf-ray
a5e2ca694fd04b67
Request
ba09d3c8…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format