@try-works/dsh-righthand 0.1.5 → 0.1.7

package/lib/sigv4.js

@@ -0,0 +1,94 @@
+/**
+ * sigv4 — AWS Signature Version 4 for Cloudflare R2 (S3-compatible API).
+ * Dependency-free: node:crypto only. Exported pure so tests pin it against
+ * the AWS published test vector.
+ * @module dsh-righthand/sigv4
+ */
+import { createHmac, createHash } from 'node:crypto';
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data).digest();
+}
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** URI-encode one path segment the S3 way. */
+function uriEncode(segment) {
+    return encodeURIComponent(segment).replace(/[!'()*]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+}
+/** Canonical URI: slashes preserved, each segment encoded. */
+function canonicalPath(pathname) {
+    if (pathname === '' || pathname === '/')
+        return '/';
+    return pathname.split('/').map(uriEncode).join('/');
+}
+/**
+ * Sign one S3 request. Returns the headers to send, including host,
+ * x-amz-content-sha256, x-amz-date and Authorization.
+ */
+export function signRequest(input) {
+    const parsed = new URL(input.url);
+    const date = input.amzDate.slice(0, 8);
+    const scope = date + '/' + input.region + '/s3/aws4_request';
+    const payloadHash = sha256Hex(input.payload);
+    const headers = {
+        ...input.headers,
+        'x-amz-content-sha256': payloadHash,
+        'x-amz-date': input.amzDate,
+    };
+    const names = Object.keys(headers).sort();
+    const canonicalHeaders = names.map(n => n + ':' + headers[n].trim() + String.fromCharCode(10)).join('');
+    const signedHeaders = names.join(';');
+    const canonicalRequest = [
+        input.method,
+        canonicalPath(parsed.pathname),
+        parsed.searchParams.toString(),
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join(String.fromCharCode(10));
+    const stringToSign = ['AWS4-HMAC-SHA256', input.amzDate, scope, sha256Hex(canonicalRequest)].join(String.fromCharCode(10));
+    const kDate = hmac('AWS4' + input.secretAccessKey, date);
+    const kRegion = hmac(kDate, input.region);
+    const kService = hmac(kRegion, 's3');
+    const kSigning = hmac(kService, 'aws4_request');
+    const signature = hmac(kSigning, stringToSign).toString('hex');
+    const authorization = 'AWS4-HMAC-SHA256 Credential=' + input.accessKeyId + '/' + scope
+        + ', SignedHeaders=' + signedHeaders
+        + ', Signature=' + signature;
+    return { headers: { ...headers, authorization } };
+}
+/**
+ * Presign a GET for query-string auth: a shareable URL valid for
+ * expiresSeconds (S3 max 7 days).
+ */
+export function presignGet(input) {
+    const parsed = new URL(input.url);
+    const date = input.amzDate.slice(0, 8);
+    const scope = date + '/' + input.region + '/s3/aws4_request';
+    const credential = input.accessKeyId + '/' + scope;
+    const query = {
+        'X-Amz-Algorithm': 'AWS4-HMAC-SHA256',
+        'X-Amz-Credential': credential,
+        'X-Amz-Date': input.amzDate,
+        'X-Amz-Expires': String(input.expiresSeconds),
+        'X-Amz-SignedHeaders': 'host',
+    };
+    const canonicalQuery = Object.keys(query).sort().map(k => uriEncode(k) + '=' + uriEncode(query[k])).join('&');
+    const canonicalRequest = [
+        'GET',
+        canonicalPath(parsed.pathname),
+        canonicalQuery,
+        'host:' + parsed.host + String.fromCharCode(10),
+        'host',
+        'UNSIGNED-PAYLOAD',
+    ].join(String.fromCharCode(10));
+    const stringToSign = ['AWS4-HMAC-SHA256', input.amzDate, scope, sha256Hex(canonicalRequest)].join(String.fromCharCode(10));
+    const kDate = hmac('AWS4' + input.secretAccessKey, date);
+    const kRegion = hmac(kDate, input.region);
+    const kService = hmac(kRegion, 's3');
+    const kSigning = hmac(kService, 'aws4_request');
+    const signature = hmac(kSigning, stringToSign).toString('hex');
+    parsed.search = canonicalQuery + '&X-Amz-Signature=' + signature;
+    return parsed.toString();
+}
+//# sourceMappingURL=sigv4.js.map

package/lib/sigv4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.js","sourceRoot":"","sources":["../src/sigv4.ts"],"names":[],"mappings":"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"}

package/lib/weather-tools.d.ts

@@ -0,0 +1,68 @@
+/**
+ * weather-tools — the worked example of the keyless data-adapter recipe
+ * (blueprint/data-adapter). Two tools over Open-Meteo, a keyless API:
+ *   rh_weather_forecast — current conditions + 3-day min/max
+ *   rh_weather_air      — PM2.5 / PM10 / European AQI
+ *
+ * Every request goes through guardedFetch, the SSRF checklist from Mu's
+ * safefetch: public destinations only (loopback, private, link-local incl.
+ * the metadata address, multicast and unspecified are refused), every
+ * redirect hop revalidated, response size and time capped.
+ * @module dsh-righthand/weather-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "righthand-weather";
+export declare const inject: string[];
+export interface WeatherConfig {
+    /** Endpoint URLs; defaults are Open-Meteo (keyless). Tests override these. */
+    forecastUrl?: string;
+    airUrl?: string;
+}
+/**
+ * Whether an IP must not be reached: the Mu safefetch set — loopback,
+ * RFC1918 private, ULA, link-local (169.254/16, fe80::/10 — which includes
+ * the 169.254.169.254 metadata address), multicast, and unspecified.
+ */
+export declare function isBlockedIP(ip: string): boolean;
+/**
+ * Fetch one URL with the SSRF checklist. `fetchImpl` and `resolve` are
+ * injectable for tests; production uses the globals.
+ */
+export declare function guardedFetch(url: string, deps?: {
+    fetchImpl?: typeof fetch;
+    resolve?: (host: string) => Promise<string[]>;
+}): Promise<string>;
+/**
+ * Normalize the Open-Meteo forecast response into a stable digest shape:
+ * what changed is the wire JSON; what callers see is this.
+ */
+export interface ForecastOut {
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    current: {
+        time: string;
+        temperature: number;
+        windspeed: number;
+        winddirection: number;
+        weathercode: number;
+    } | null;
+    daily: {
+        time: string[];
+        temperatureMax: number[];
+        temperatureMin: number[];
+    };
+}
+export declare function normalizeForecast(json: any): ForecastOut;
+/** Normalize the Open-Meteo air-quality response. */
+export interface AirOut {
+    latitude: number;
+    longitude: number;
+    time: string;
+    pm2_5: number | null;
+    pm10: number | null;
+    aqi: number | null;
+}
+export declare function normalizeAir(json: any): AirOut;
+export declare function apply(ctx: Context, config?: WeatherConfig): void;
+//# sourceMappingURL=weather-tools.d.ts.map

package/lib/weather-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weather-tools.d.ts","sourceRoot":"","sources":["../src/weather-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,eAAO,MAAM,IAAI,sBAAsB,CAAA;AACvC,eAAO,MAAM,MAAM,UAAY,CAAA;AAE/B,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAWD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAoB/C;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAAO,GACrF,OAAO,CAAC,MAAM,CAAC,CAgCjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACpH,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC9E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,WAAW,CAmBxD;AAED,qDAAqD;AACrD,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAW9C;AAED,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,aAAkB,GAAG,IAAI,CAyEpE"}

package/lib/weather-tools.js

@@ -0,0 +1,208 @@
+/**
+ * weather-tools — the worked example of the keyless data-adapter recipe
+ * (blueprint/data-adapter). Two tools over Open-Meteo, a keyless API:
+ *   rh_weather_forecast — current conditions + 3-day min/max
+ *   rh_weather_air      — PM2.5 / PM10 / European AQI
+ *
+ * Every request goes through guardedFetch, the SSRF checklist from Mu's
+ * safefetch: public destinations only (loopback, private, link-local incl.
+ * the metadata address, multicast and unspecified are refused), every
+ * redirect hop revalidated, response size and time capped.
+ * @module dsh-righthand/weather-tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+export const name = 'righthand-weather';
+export const inject = ['tools'];
+const DEFAULTS = {
+    forecastUrl: 'https://api.open-meteo.com/v1/forecast',
+    airUrl: 'https://air-quality-api.open-meteo.com/v1/air-quality',
+};
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const FETCH_TIMEOUT_MS = 10000;
+/**
+ * Whether an IP must not be reached: the Mu safefetch set — loopback,
+ * RFC1918 private, ULA, link-local (169.254/16, fe80::/10 — which includes
+ * the 169.254.169.254 metadata address), multicast, and unspecified.
+ */
+export function isBlockedIP(ip) {
+    if (ip === '')
+        return true;
+    if (isIP(ip) === 4) {
+        const [a, b] = ip.split('.').map(Number);
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a >= 224 && a <= 239)
+            return true;
+        return false;
+    }
+    if (isIP(ip) === 6) {
+        const lower = ip.toLowerCase();
+        if (lower === '::' || lower === '::1')
+            return true;
+        if (lower.startsWith('fc') || lower.startsWith('fd'))
+            return true;
+        if (lower.startsWith('fe8') || lower.startsWith('fe9') || lower.startsWith('fea') || lower.startsWith('feb'))
+            return true;
+        if (lower.startsWith('ff'))
+            return true;
+        return false;
+    }
+    return true;
+}
+/**
+ * Fetch one URL with the SSRF checklist. `fetchImpl` and `resolve` are
+ * injectable for tests; production uses the globals.
+ */
+export async function guardedFetch(url, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const resolve = deps.resolve ?? (async (host) => (await lookup(host, { all: true })).map(a => a.address));
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const parsed = new URL(current);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            throw new Error('blocked: non-http(s) URL');
+        const ips = await resolve(parsed.hostname);
+        if (ips.length === 0 || ips.some(isBlockedIP))
+            throw new Error('blocked: destination is not a public host');
+        const res = await fetchImpl(current, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), redirect: 'manual' });
+        if (res.status >= 300 && res.status < 400) {
+            const next = res.headers.get('location');
+            if (next === null)
+                throw new Error('blocked: redirect without location');
+            current = new URL(next, current).toString();
+            continue;
+        }
+        if (!res.ok)
+            throw new Error('HTTP ' + res.status + ' for ' + current);
+        const reader = res.body?.getReader();
+        if (reader === undefined)
+            return '';
+        const chunks = [];
+        let bytes = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.length;
+            if (bytes > MAX_BODY_BYTES)
+                throw new Error('response exceeds ' + MAX_BODY_BYTES + ' bytes');
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    throw new Error('too many redirects');
+}
+export function normalizeForecast(json) {
+    const cw = json.current_weather;
+    return {
+        latitude: Number(json.latitude ?? 0),
+        longitude: Number(json.longitude ?? 0),
+        timezone: json.timezone ?? '',
+        current: cw ? {
+            time: String(cw.time ?? ''),
+            temperature: Number(cw.temperature ?? 0),
+            windspeed: Number(cw.windspeed ?? 0),
+            winddirection: Number(cw.winddirection ?? 0),
+            weathercode: Number(cw.weathercode ?? 0),
+        } : null,
+        daily: {
+            time: (json.daily?.time ?? []).map(String),
+            temperatureMax: (json.daily?.temperature_2m_max ?? []).map(Number),
+            temperatureMin: (json.daily?.temperature_2m_min ?? []).map(Number),
+        },
+    };
+}
+export function normalizeAir(json) {
+    const c = json.current ?? {};
+    const num = (v) => (v === undefined || v === null ? null : Number(v));
+    return {
+        latitude: Number(json.latitude ?? 0),
+        longitude: Number(json.longitude ?? 0),
+        time: String(c.time ?? ''),
+        pm2_5: num(c.pm2_5),
+        pm10: num(c.pm10),
+        aqi: num(c.european_aqi),
+    };
+}
+export function apply(ctx, config = {}) {
+    const cfg = { ...DEFAULTS, ...config };
+    ctx.tools.register(defineTool({
+        name: 'rh_weather_forecast',
+        description: 'Weather forecast for a location from Open-Meteo (keyless): current conditions plus 3 days of min/max temperatures.',
+        parameters: {
+            latitude: { type: 'number', required: true, description: 'Latitude, e.g. 51.5074 for London.' },
+            longitude: { type: 'number', required: true, description: 'Longitude, e.g. -0.1278 for London.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    latitude: { type: 'number', required: true },
+                    longitude: { type: 'number', required: true },
+                    timezone: { type: 'string', required: true },
+                    current: { type: 'json' },
+                    daily: { type: 'json', required: true },
+                },
+            },
+            render: (_args, value) => { const c = value.current; return [{ type: 'text', text: c ? (value.timezone + ': ' + c.temperature + ' C, wind ' + c.windspeed + ' km/h') : value.timezone + ': current conditions unavailable' }]; },
+        },
+        async execute(args) {
+            const url = cfg.forecastUrl
+                + '?latitude=' + args.latitude
+                + '&longitude=' + args.longitude
+                + '&current_weather=true&daily=temperature_2m_max,temperature_2m_min&forecast_days=3';
+            const body = await guardedFetch(url);
+            return normalizeForecast(JSON.parse(body));
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'rh_weather_air',
+        description: 'Air quality at a location from Open-Meteo (keyless): PM2.5, PM10 and the European AQI.',
+        parameters: {
+            latitude: { type: 'number', required: true, description: 'Latitude.' },
+            longitude: { type: 'number', required: true, description: 'Longitude.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    latitude: { type: 'number', required: true },
+                    longitude: { type: 'number', required: true },
+                    time: { type: 'string', required: true },
+                    pm2_5: { type: 'number' },
+                    pm10: { type: 'number' },
+                    aqi: { type: 'number' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: 'PM2.5 ' + value.pm2_5 + ', PM10 ' + value.pm10 + ', AQI ' + value.aqi }],
+        },
+        async execute(args) {
+            const url = cfg.airUrl
+                + '?latitude=' + args.latitude
+                + '&longitude=' + args.longitude
+                + '&current=pm2_5,pm10,european_aqi';
+            const body = await guardedFetch(url);
+            const out = normalizeAir(JSON.parse(body));
+            return {
+                latitude: out.latitude,
+                longitude: out.longitude,
+                time: out.time,
+                ...out.pm2_5 !== null ? { pm2_5: out.pm2_5 } : {},
+                ...out.pm10 !== null ? { pm10: out.pm10 } : {},
+                ...out.aqi !== null ? { aqi: out.aqi } : {},
+            };
+        },
+    }));
+}
+//# sourceMappingURL=weather-tools.js.map

package/lib/weather-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weather-tools.js","sourceRoot":"","sources":["../src/weather-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-righthand",
   "description": "DeepSeek Harness plugin: DSH-native righthand tools — durable KV store, credential/settings management, governed exec, and a tool guard",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/skills/dsh-righthand/SKILL.md

@@ -17,6 +17,8 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 | settings | `rh_settings_get` / `rh_settings_set` | `ctx.settings` (namespace `righthand`) | Reading or patching righthand settings (`accountId`, `defaultZone`, `defaultScriptPrefix`). |
 | exec | `rh_run` / `rh_run_bg` | `ctx.subprocess` + `ctx.jobs` | Running one command (argv array, no shell interpretation). `rh_run` collects bounded output; `rh_run_bg` starts an owner-scoped background job and returns its id. |
 | text | `rh_text_summarise` / `rh_text_extract` / `rh_text_classify` / `rh_text_translate` | `ctx.llm` (one model call per verb) | Language work: shorten, turn into JSON matching a schema, sort into your labels with confidence, or translate preserving formatting. |
+| weather | `rh_weather_forecast` / `rh_weather_air` | Open-Meteo (keyless) via the SSRF-guarded fetcher | Current conditions + 3-day min/max, or PM2.5/PM10/AQI, for a lat/lon. Keyless only — anything needing an API token is out of scope. |
+| files | `rh_files_put` / `rh_files_get` / `rh_files_list` / `rh_files_share` / `rh_files_delete` | Cloudflare R2 (the user's own account) | Store/read/list/share/delete objects in an R2 bucket. `rh_files_share` returns a presigned download URL valid for N minutes (default 60, max 7 days) — anyone with the URL can read it for that window. |
 | guard | (policy, not a tool) | `ctx.tools` `tools/pre-execute` | Configured via plugin config `rules`; gates tools by name prefix with `allow` / `deny` / `ask` modes. |
 
 ## Store semantics
@@ -25,6 +27,19 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 - `rh_store_get` returns `{ found, key, value?, updatedAt? }` — `found: false` means the key is absent, not an error.
 - Writes are durable (backend flush before commit) and serialized on one write chain; values must be JSON-serializable.
 
+## Files semantics
+
+- Cloudflare R2, the user's own account: accountId from settings, credentials `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` from the credential provider, bucket from settings `defaultR2Bucket` (or plugin config).
+- Every request is SigV4-signed (region `auto`); the signer is pinned to the AWS published test vector.
+- Content is text (`text/plain` default, override with `contentType`); `rh_files_get` returns `found: false` for absent keys, not an error.
+- `rh_files_share` presigns a GET — treat the URL as a secret for its validity window.
+
+## Weather semantics
+
+- Keyless only: Open-Meteo, no token. Every request goes through `guardedFetch` — public destinations only (loopback/private/link-local/multicast refused), every redirect hop revalidated, size and time capped.
+- Results are normalized to a stable shape (the wire JSON is the provider's; callers see ours).
+- Output schemas reject `null` — absent pollutant values are omitted, not null.
+
 ## Text semantics
 
 - One model call per verb; each call's failure is contained (the other tools are unaffected).
@@ -52,6 +67,7 @@ The righthand toolkit: DSH-native tools over the harness's own services. Use thi
 | `accountId` | `""` | Cloudflare account id used by righthand Cloudflare tools |
 | `defaultScriptPrefix` | `"rh-"` | default name prefix for generated workers/scripts |
 | `defaultZone` | `""` | default Cloudflare zone |
+| `defaultR2Bucket` | `""` | default R2 bucket for `rh_files_*` |
 
 ## Guard policy
 
@@ -61,5 +77,5 @@ Rules come from the plugin config (`rules: [{ toolPrefix, mode, ask?, destructiv
 
 ## Service availability
 
-- **web profile**: all twenty tools register (`storageDomain` is provided by the web app rows).
+- **web profile**: all twenty-seven tools register (`storageDomain` is provided by the web app rows).
 - **other profiles** (e.g. headless): the store and task families stay dormant; the other seven tools still register. The plugin never fails the boot.