@try-works/dsh-righthand 0.1.5 → 0.1.7

package/src/files-tools.ts

@@ -0,0 +1,294 @@
+/**
+ * files-tools — rh_files_* over Cloudflare R2 (the user's own account).
+ * The first family on an actual Cloudflare primitive. S3-compatible API,
+ * signed with SigV4 (src/sigv4.ts, pinned to the AWS test vector).
+ *
+ * Credentials resolve at call time from the credential provider
+ * (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY); accountId and bucket come
+ * from the righthand settings namespace. The client is a pure factory so
+ * tests drive it with a stubbed fetch.
+ * @module dsh-righthand/files-tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { signRequest, presignGet } from './sigv4.ts'
+
+export const name = 'righthand-files'
+export const inject = ['tools', 'credentials', 'settings']
+
+export const R2_ACCESS_KEY_REF = 'R2_ACCESS_KEY_ID'
+export const R2_SECRET_KEY_REF = 'R2_SECRET_ACCESS_KEY'
+
+export interface FilesConfig {
+  /** Bucket name; defaults to the righthand settings defaultR2Bucket. */
+  bucket?: string
+}
+
+export interface R2Options {
+  accountId: string
+  accessKeyId: string
+  secretAccessKey: string
+  bucket: string
+  fetchImpl?: typeof fetch
+  now?: () => Date
+}
+
+function amzDate(d: Date): string {
+  return d.toISOString().replace(/[:-]|\.\d{3}/g, '')
+}
+
+export interface ListEntry {
+  key: string
+  size: number
+  lastModified: string
+}
+
+/** Minimal ListObjectsV2 XML parse: Key / Size / LastModified triples. */
+function parseListXml(xml: string): ListEntry[] {
+  const out: ListEntry[] = []
+  const contents = xml.split('<Contents>').slice(1)
+  for (const block of contents) {
+    const grab = (tag: string): string => {
+      const a = block.indexOf('<' + tag + '>')
+      const b = block.indexOf('</' + tag + '>')
+      return a < 0 || b < 0 ? '' : block.slice(a + tag.length + 2, b)
+    }
+    const key = grab('Key')
+    if (key === '') continue
+    out.push({ key, size: Number(grab('Size') ?? 0), lastModified: grab('LastModified') })
+  }
+  return out
+}
+
+/**
+ * The R2 client factory. Pure over its options; every call signs fresh.
+ */
+export function createR2Client(opts: R2Options) {
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const now = opts.now ?? (() => new Date())
+  const base = 'https://' + opts.accountId + '.r2.cloudflarestorage.com/' + opts.bucket
+
+  async function request(method: string, key: string, payload: string, extraHeaders: Record<string, string> = {}): Promise<Response> {
+    const url = base + '/' + key
+    const parsed = new URL(url)
+    const signed = signRequest({
+      method,
+      url,
+      headers: { host: parsed.host, ...extraHeaders },
+      payload,
+      accessKeyId: opts.accessKeyId,
+      secretAccessKey: opts.secretAccessKey,
+      region: 'auto',
+      amzDate: amzDate(now()),
+    })
+    return fetchImpl(url, { method, headers: signed.headers, body: payload === '' ? undefined : payload })
+  }
+
+  return {
+    async put(key: string, content: string, contentType?: string): Promise<{ key: string; size: number }> {
+      const res = await request('PUT', key, content, contentType ? { 'content-type': contentType } : {})
+      if (!res.ok) throw new Error('R2 PUT failed: HTTP ' + res.status)
+      return { key, size: Buffer.byteLength(content) }
+    },
+
+    async get(key: string): Promise<{ found: boolean; content: string; contentType: string }> {
+      const res = await request('GET', key, '')
+      if (res.status === 404) return { found: false, content: '', contentType: '' }
+      if (!res.ok) throw new Error('R2 GET failed: HTTP ' + res.status)
+      return { found: true, content: await res.text(), contentType: res.headers.get('content-type') ?? '' }
+    },
+
+    async list(prefix?: string, maxKeys?: number): Promise<ListEntry[]> {
+      const q = '?list-type=2' + (prefix ? '&prefix=' + encodeURIComponent(prefix) : '') + (maxKeys ? '&max-keys=' + maxKeys : '')
+      const url = base + '/' + q
+      const parsed = new URL(url)
+      const signed = signRequest({
+        method: 'GET',
+        url,
+        headers: { host: parsed.host },
+        payload: '',
+        accessKeyId: opts.accessKeyId,
+        secretAccessKey: opts.secretAccessKey,
+        region: 'auto',
+        amzDate: amzDate(now()),
+      })
+      const res = await fetchImpl(url, { method: 'GET', headers: signed.headers })
+      if (!res.ok) throw new Error('R2 list failed: HTTP ' + res.status)
+      return parseListXml(await res.text())
+    },
+
+    share(key: string, expiresSeconds: number): string {
+      return presignGet({
+        url: base + '/' + key,
+        accessKeyId: opts.accessKeyId,
+        secretAccessKey: opts.secretAccessKey,
+        region: 'auto',
+        amzDate: amzDate(now()),
+        expiresSeconds,
+      })
+    },
+
+    async delete(key: string): Promise<{ key: string; existed: boolean }> {
+      const res = await request('DELETE', key, '')
+      if (res.status === 404) return { key, existed: false }
+      if (!res.ok) throw new Error('R2 DELETE failed: HTTP ' + res.status)
+      return { key, existed: true }
+    },
+  }
+}
+
+
+export function apply(ctx: Context, config: FilesConfig = {}): void {
+  const ns = settingsNamespace('righthand')
+
+  /** Resolve accountId + credentials + bucket at call time. */
+  async function client(): Promise<ReturnType<typeof createR2Client>> {
+    const settings = ctx.settings.get(ns) as { accountId?: string; defaultR2Bucket?: string } | undefined
+    const accountId = settings?.accountId ?? ''
+    if (accountId === '') throw new Error('righthand accountId is not set (rh_settings_set { accountId })')
+    const bucket = config.bucket ?? settings?.defaultR2Bucket ?? ''
+    if (bucket === '') throw new Error('R2 bucket is not set (plugin config bucket or settings defaultR2Bucket)')
+    const access = await ctx.credentials.resolve(credentialRef(R2_ACCESS_KEY_REF))
+    const secret = await ctx.credentials.resolve(credentialRef(R2_SECRET_KEY_REF))
+    if (access === undefined || secret === undefined) {
+      throw new Error('R2 credentials are not set (rh_credential_set R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY)')
+    }
+    return createR2Client({ accountId, accessKeyId: access.value, secretAccessKey: secret.value, bucket })
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_put',
+    description: 'Store a file in the R2 bucket and return its key. Content is text (reports, CSV, transcripts, code); content type defaults to text/plain.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'Object key, e.g. reports/2026-08-30.csv.' },
+      content: { type: 'string', required: true, description: 'The full text content to store.' },
+      contentType: { type: 'string', description: 'Content type, e.g. text/csv. Defaults to text/plain.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          size: { type: 'integer', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'stored ' + value.key + ' (' + value.size + ' bytes)' }],
+    },
+    async execute(args) {
+      const c = await client()
+      return c.put(args.key, args.content, args.contentType)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_get',
+    description: 'Read a stored file back by its key. found: false means the key is absent, not an error.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to read.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          found: { type: 'boolean', required: true },
+          key: { type: 'string', required: true },
+          content: { type: 'string' },
+          contentType: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.found && typeof value.content === 'string' ? value.content : '(absent)' }],
+    },
+    async execute(args) {
+      const c = await client()
+      const out = await c.get(args.key)
+      return {
+        key: args.key,
+        found: out.found,
+        ...out.found ? { content: out.content, contentType: out.contentType } : {},
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_list',
+    description: 'List objects in the bucket, optionally by key prefix. Newest first is not guaranteed by S3; entries carry lastModified.',
+    parameters: {
+      prefix: { type: 'string', description: 'Only keys starting with this, e.g. reports/.' },
+      maxKeys: { type: 'integer', description: 'Max entries (default 100).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          entries: { type: 'array', required: true, items: { type: 'json' } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.entries.length + ' objects' }],
+    },
+    async execute(args) {
+      const c = await client()
+      const entries = await c.list(args.prefix, args.maxKeys)
+      return { entries: entries as any[] }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_share',
+    description: 'Get a presigned download URL for a key, valid for the given minutes (default 60, max 10080). Anyone with the URL can read the object for that window.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to share.' },
+      minutes: { type: 'integer', description: 'Validity in minutes (default 60, max 10080 = 7 days).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          url: { type: 'string', required: true },
+          expiresAt: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.url }],
+    },
+    async execute(args) {
+      const minutes = Math.min(Math.max(args.minutes ?? 60, 1), 10080)
+      const c = await client()
+      const url = c.share(args.key, minutes * 60)
+      return { key: args.key, url, expiresAt: new Date(Date.now() + minutes * 60000).toISOString() }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'rh_files_delete',
+    description: 'Delete an object by key. Returns whether it existed.',
+    parameters: {
+      key: { type: 'string', required: true, description: 'The object key to delete.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          key: { type: 'string', required: true },
+          existed: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: 'deleted ' + value.key + ': ' + value.existed }],
+    },
+    async execute(args) {
+      const c = await client()
+      return c.delete(args.key)
+    },
+  }))
+}
+
+
+
+

package/src/index.ts

@@ -16,6 +16,8 @@
  * - secrets-tools:   rh_credential_describe/set/unset + rh_settings_get/set
  * - task-tools:      rh_task_create/list/next/update/delete over ctx.storageDomain
  * - text-tools:      rh_text_summarise/extract/classify/translate over ctx.llm
+ * - weather-tools:   rh_weather_forecast/air over Open-Meteo (keyless, SSRF-guarded)
+ * - files-tools:     rh_files_put/get/list/share/delete over Cloudflare R2
  * - exec-tools:      rh_run / rh_run_bg over ctx.subprocess + ctx.jobs
  * - guard-tools:     tools/pre-execute policy (config.rules)
  * - skills:          the packaged dsh-righthand skill (ctx.skills)
@@ -30,6 +32,8 @@ import * as execTools from './exec-tools.ts'
 import * as guardTools from './guard-tools.ts'
 import * as taskTools from './task-tools.ts'
 import * as textTools from './text-tools.ts'
+import * as weatherTools from './weather-tools.ts'
+import * as filesTools from './files-tools.ts'
 import * as righthandSkills from './skills.ts'
 import type { GuardRule } from './guard-tools.ts'
 
@@ -56,14 +60,21 @@ export function apply(ctx: Context, config: RighthandConfig = {}): void {
   ctx.plugin(execTools)
   ctx.plugin(taskTools)
   ctx.plugin(textTools)
+  ctx.plugin(weatherTools)
+  ctx.plugin(filesTools)
   ctx.plugin(guardTools, { rules: config.rules ?? [] })
   ctx.plugin(righthandSkills)
 }
 
 // Individual modules stay importable for selective mounting.
-export { storeTools, secretsTools, execTools, taskTools, textTools, guardTools, righthandSkills }
+export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, filesTools, guardTools, righthandSkills }
 export { SKILL_NAME, SKILL_DESCRIPTION, skillDirectory, skillBody } from './skills.ts'
 export type { GuardRule } from './guard-tools.ts'
 export { guardFactsFor } from './guard-tools.ts'
 export type { GuardFacts } from './guard-tools.ts'
+export { isBlockedIP, guardedFetch, normalizeForecast, normalizeAir } from './weather-tools.ts'
+export { createR2Client, R2_ACCESS_KEY_REF, R2_SECRET_KEY_REF } from './files-tools.ts'
+export { signRequest, presignGet } from './sigv4.ts'
+export type { R2Options, ListEntry } from './files-tools.ts'
+export type { WeatherConfig, ForecastOut, AirOut } from './weather-tools.ts'
 

package/src/secrets-tools.ts

@@ -27,6 +27,7 @@ export const righthandSettingsSchema = z.object({
   accountId: z.string().default(''),
   defaultScriptPrefix: z.string().default('rh-'),
   defaultZone: z.string().default(''),
+  defaultR2Bucket: z.string().default(''),
 })
 
 /** Register the settings namespace + the secret/credential tools. */
@@ -119,7 +120,7 @@ export function apply(ctx: Context): void {
     },
     async execute() {
       const v = scope.get()
-      return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone }
+      return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone, defaultR2Bucket: v.defaultR2Bucket }
     },
   }))
 

package/src/sigv4.ts

@@ -0,0 +1,122 @@
+/**
+ * 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: Buffer | string, data: string): Buffer {
+  return createHmac('sha256', key).update(data).digest()
+}
+
+function sha256Hex(data: string): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** URI-encode one path segment the S3 way. */
+function uriEncode(segment: string): string {
+  return encodeURIComponent(segment).replace(/[!'()*]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase())
+}
+
+/** Canonical URI: slashes preserved, each segment encoded. */
+function canonicalPath(pathname: string): string {
+  if (pathname === '' || pathname === '/') return '/'
+  return pathname.split('/').map(uriEncode).join('/')
+}
+
+export interface SignRequestInput {
+  method: string
+  /** Full URL, e.g. https://<account>.r2.cloudflarestorage.com/<bucket>/<key> */
+  url: string
+  /** Headers to sign (lowercase names), e.g. host, content-type. */
+  headers: Record<string, string>
+  /** Exact payload bytes; '' for GET/DELETE without a body. */
+  payload: string
+  accessKeyId: string
+  secretAccessKey: string
+  /** R2 uses region 'auto'. */
+  region: string
+  /** yyyyMMdd'T'HHmmss'Z' — injectable for tests. */
+  amzDate: string
+}
+
+export interface SignedRequest {
+  headers: Record<string, string>
+}
+
+/**
+ * Sign one S3 request. Returns the headers to send, including host,
+ * x-amz-content-sha256, x-amz-date and Authorization.
+ */
+export function signRequest(input: SignRequestInput): SignedRequest {
+  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: Record<string, string> = {
+    ...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: Omit<SignRequestInput, 'method' | 'headers' | 'payload'> & { expiresSeconds: number }): string {
+  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: Record<string, string> = {
+    '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()
+}
+
+