Skip to content

Commit 17f6ebe

Browse files
Jonathan D.A. Jewellclaude
andcommitted
feat(bindings): add lower priority language bindings batch 1
- Add Odin bindings with idiomatic multiple return values - Add Forth bindings with stack-based operations - Both implement full 6-module structure: * SafeMath: overflow-checked arithmetic * SafeString: XSS prevention, escaping * SafePath: traversal detection * SafeEmail: RFC validation * SafeNetwork: IP classification * SafeCrypto: hashing, secure random Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 619aa94 commit 17f6ebe

9 files changed

Lines changed: 1989 additions & 0 deletions

File tree

bindings/forth/README.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Proven for Forth
2+
3+
Safe, validated operations library for Forth applications.
4+
5+
## Installation
6+
7+
Include the library in your Forth program:
8+
9+
```forth
10+
include proven.fs
11+
```
12+
13+
## Usage
14+
15+
```forth
16+
include proven.fs
17+
18+
\ Safe math with overflow checking
19+
1000000000 2000000000 safe+ . \ prints result
20+
\ flag on stack: 0 = ok, -1 = overflow
21+
22+
\ XSS prevention
23+
s" <script>alert('xss')</script>" escape-html type
24+
\ prints: &lt;script&gt;alert('xss')&lt;/script&gt;
25+
26+
\ Path safety
27+
s" ../../../etc/passwd" has-traversal? if
28+
." Dangerous path!" cr
29+
then
30+
31+
\ Email validation
32+
s" user@example.com" valid-email? if
33+
." Valid email" cr
34+
then
35+
36+
\ IP parsing
37+
s" 192.168.1.1" parse-ipv4 if
38+
ip-private? if
39+
." Private network" cr
40+
then
41+
then
42+
43+
\ Port validation
44+
8080 valid-port? if
45+
." Valid port" cr
46+
then
47+
```
48+
49+
## Stack Effects
50+
51+
All words document their stack effects in standard Forth notation.
52+
53+
### SafeMath
54+
55+
Overflow-checked arithmetic operations:
56+
57+
```forth
58+
\ All operations return ( result flag ) where flag is 0 for ok, -1 for overflow
59+
60+
safe+ ( a b -- result flag ) \ Add with overflow check
61+
safe- ( a b -- result flag ) \ Subtract with overflow check
62+
safe* ( a b -- result flag ) \ Multiply with overflow check
63+
safe/ ( a b -- result flag ) \ Divide with zero check
64+
safe-mod ( a b -- result flag ) \ Modulo with zero check
65+
safe-abs ( a -- result flag ) \ Absolute value
66+
safe-negate ( a -- result flag ) \ Negate
67+
68+
clamp ( value min max -- clamped ) \ Clamp to range
69+
in-range? ( value min max -- flag ) \ Check if in range
70+
```
71+
72+
### SafeString
73+
74+
XSS prevention and string sanitization:
75+
76+
```forth
77+
escape-html ( addr len -- addr' len' ) \ Escape HTML entities
78+
escape-sql ( addr len -- addr' len' ) \ Escape SQL quotes
79+
sanitize-default ( addr len -- addr' len' ) \ Keep only alphanumeric + _-
80+
```
81+
82+
### SafePath
83+
84+
Directory traversal protection:
85+
86+
```forth
87+
has-traversal? ( addr len -- flag ) \ Check for traversal
88+
sanitize-filename ( addr len -- addr' len' ) \ Remove dangerous chars
89+
```
90+
91+
### SafeEmail
92+
93+
Email validation:
94+
95+
```forth
96+
valid-email? ( addr len -- flag ) \ Basic email format check
97+
find-at ( addr len -- pos ) \ Find @ position (-1 if not found)
98+
```
99+
100+
### SafeNetwork
101+
102+
IP address validation and classification:
103+
104+
```forth
105+
parse-ipv4 ( addr len -- flag ) \ Parse IP, store in ip-a/b/c/d
106+
ip-loopback? ( -- flag ) \ Check if parsed IP is loopback
107+
ip-private? ( -- flag ) \ Check if parsed IP is private
108+
valid-port? ( port -- flag ) \ Check port in range 1-65535
109+
privileged-port? ( port -- flag ) \ Check port < 1024
110+
```
111+
112+
### SafeCrypto
113+
114+
Basic cryptographic operations:
115+
116+
```forth
117+
simple-hash ( addr len -- hash ) \ Simple XOR hash (demo only)
118+
constant-time= ( addr1 addr2 len -- flag ) \ Timing-safe compare
119+
```
120+
121+
**Note:** The crypto operations are simplified for demonstration. Use a proper cryptographic library for production applications.
122+
123+
## Examples
124+
125+
### Overflow-Safe Calculation
126+
127+
```forth
128+
\ Calculate factorial with overflow detection
129+
: safe-factorial ( n -- result flag )
130+
dup 0= if drop 1 0 exit then
131+
1 0 \ result flag
132+
rot 1+ 1 do
133+
swap i safe*
134+
dup if \ overflow?
135+
nip nip unloop exit
136+
then
137+
drop swap
138+
loop
139+
swap drop
140+
;
141+
142+
20 safe-factorial .s \ Should show large result and 0 (ok)
143+
21 safe-factorial .s \ May overflow
144+
```
145+
146+
### Input Sanitization
147+
148+
```forth
149+
\ Sanitize user input for display
150+
: safe-display ( addr len -- )
151+
escape-html type
152+
;
153+
154+
s" User said: <script>evil()</script>" safe-display
155+
\ Output: User said: &lt;script&gt;evil()&lt;/script&gt;
156+
```
157+
158+
### Path Validation
159+
160+
```forth
161+
\ Safe file access
162+
: safe-open ( addr len -- fid flag )
163+
2dup has-traversal? if
164+
2drop 0 -1 \ return error
165+
else
166+
r/o open-file \ open normally
167+
then
168+
;
169+
```
170+
171+
## Compatibility
172+
173+
This library uses standard ANS Forth words and should work with:
174+
- Gforth
175+
- SwiftForth
176+
- VFX Forth
177+
- Other ANS-compliant implementations
178+
179+
## License
180+
181+
PMPL-1.0

0 commit comments

Comments
 (0)